Adapt docs to MyST

.github/workflows/tools-api-docs-dev.yml

@@ -1,7 +1,6 @@
 name: nf-core/tools dev API docs
-on:
-  push:
-    branches: [dev]
+# Run on push and PR to test that docs build
+on: [pull_request, push]
 
 jobs:
   api-docs:
@@ -27,7 +26,8 @@ jobs:
         run: make --directory ./docs/api html
 
       - name: Sync dev docs
-        if: github.repository == 'nf-core/tools'
+        # Only sync with the website if it was a push from nf-core/tools dev branch
+        if: github.repository == 'nf-core/tools' && github.event.type == 'push' && github.event.base_ref == 'refs/heads/dev'
         uses: SamKirkland/FTP-Deploy-Action@4.0.0
         with:
           server: ${{ secrets.ftp_server }}

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ### General
 
+* Convert nf-core/tools API / lint test documentation to MyST ([#1245](https://github.com/nf-core/tools/pull/1245))
+
 ### Modules
 
 ## [v2.3 - Mercury Vulture](https://github.com/nf-core/tools/releases/tag/2.3) - [2022-03-15]

docs/api/_src/api/bump_version.rst → docs/api/_src/api/bump_version.md

@@ -1,8 +1,9 @@
-nf_core.bump_version
-====================
+# nf_core.bump_version
 
+```{eval-rst}
 .. automodule:: nf_core.bump_version
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/create.rst → docs/api/_src/api/create.md

@@ -1,8 +1,9 @@
-nf_core.create
-==============
+# nf_core.create
 
+```{eval-rst}
 .. automodule:: nf_core.create
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/download.rst → docs/api/_src/api/download.md

@@ -1,8 +1,9 @@
-nf_core.download
-================
+# nf_core.download
 
+```{eval-rst}
 .. automodule:: nf_core.download
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/index.md

@@ -0,0 +1,9 @@
+# API Reference
+
+```{toctree}
+:caption: 'Tests:'
+:glob: true
+:maxdepth: 2
+
+*
+```

docs/api/_src/api/launch.rst → docs/api/_src/api/launch.md

@@ -1,8 +1,9 @@
-nf_core.launch
-==============
+# nf_core.launch
 
+```{eval-rst}
 .. automodule:: nf_core.launch
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/licences.rst → docs/api/_src/api/licences.md

@@ -1,8 +1,9 @@
-nf_core.licences
-================
+# nf_core.licences
 
+```{eval-rst}
 .. automodule:: nf_core.licences
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/lint.rst → docs/api/_src/api/lint.md

@@ -1,14 +1,19 @@
-nf_core.lint
-============
+# nf_core.lint
 
-.. seealso:: See the `Lint Tests <../lint_tests/index.html>`_ docs for information about specific linting functions.
+:::{seealso}
+See the [Lint Tests](../lint_tests/index.html) docs for information about specific linting functions.
+:::
 
+```{eval-rst}
 .. automodule:: nf_core.lint
     :members: run_linting
     :undoc-members:
     :show-inheritance:
+```
 
+```{eval-rst}
 .. autoclass:: nf_core.lint.PipelineLint
     :members: _lint_pipeline
     :private-members: _print_results, _get_results_md, _save_json_results, _wrap_quotes, _strip_ansi_codes
     :show-inheritance:
+```

docs/api/_src/api/list.rst → docs/api/_src/api/list.md

@@ -1,8 +1,9 @@
-nf_core.list
-============
+# nf_core.list
 
+```{eval-rst}
 .. automodule:: nf_core.list
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/modules.rst → docs/api/_src/api/modules.md

@@ -1,8 +1,9 @@
-nf_core.modules
-===============
+# nf_core.modules
 
+```{eval-rst}
 .. automodule:: nf_core.modules
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/schema.rst → docs/api/_src/api/schema.md

@@ -1,8 +1,9 @@
-nf_core.schema
-==============
+# nf_core.schema
 
+```{eval-rst}
 .. automodule:: nf_core.schema
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/sync.rst → docs/api/_src/api/sync.md

@@ -1,8 +1,9 @@
-nf_core.sync
-==============
+# nf_core.sync
 
+```{eval-rst}
 .. automodule:: nf_core.sync
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/api/utils.rst → docs/api/_src/api/utils.md

@@ -1,8 +1,9 @@
-nf_core.utils
-=============
+# nf_core.utils
 
+```{eval-rst}
 .. automodule:: nf_core.utils
     :members:
     :undoc-members:
     :show-inheritance:
     :private-members:
+```

docs/api/_src/conf.py

@@ -39,7 +39,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+extensions = ["myst_parser", "sphinx.ext.autodoc", "sphinx.ext.napoleon"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["./_templates"]

docs/api/_src/index.md

@@ -0,0 +1,24 @@
+# nf-core/tools documentation
+
+```{toctree}
+:caption: 'Contents:'
+:glob: true
+:hidden: true
+:maxdepth: 2
+
+pipeline_lint_tests/index.rst
+module_lint_tests/index.rst
+api/index.rst
+```
+
+This documentation is for the `nf-core/tools` package.
+
+Primarily, it describes the different [code lint tests](lint_tests/index.html)
+run by `nf-core lint` (typically visited by a developer when their pipeline fails a given
+test), and also reference for the `nf_core` [Python package API](api/index.html).
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+- {ref}`search`

docs/api/_src/pipeline_lint_tests/actions_awsfulltest.rst → docs/api/_src/pipeline_lint_tests/actions_awsfulltest.md

@@ -1,4 +1,5 @@
-actions_awsfulltest
-===================
+# actions_awsfulltest
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.actions_awsfulltest
+```

docs/api/_src/pipeline_lint_tests/actions_awstest.rst → docs/api/_src/pipeline_lint_tests/actions_awstest.md

@@ -1,4 +1,5 @@
-actions_awstest
-===============
+# actions_awstest
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.actions_awstest
+```

docs/api/_src/pipeline_lint_tests/actions_ci.rst → docs/api/_src/pipeline_lint_tests/actions_ci.md

@@ -1,4 +1,5 @@
-actions_ci
-==========
+# actions_ci
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.actions_ci
+```

docs/api/_src/pipeline_lint_tests/actions_schema_validation.rst → docs/api/_src/pipeline_lint_tests/actions_schema_validation.md

@@ -1,4 +1,5 @@
-actions_schema_validation
-=========================
+# actions_schema_validation
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.actions_schema_validation
+```

docs/api/_src/pipeline_lint_tests/files_exist.rst → docs/api/_src/pipeline_lint_tests/files_exist.md

@@ -1,5 +1,5 @@
-files_exist
-===========
+# files_exist
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.files_exist
-
+```

docs/api/_src/pipeline_lint_tests/files_unchanged.rst → docs/api/_src/pipeline_lint_tests/files_unchanged.md

@@ -1,4 +1,5 @@
-files_unchanged
-===============
+# files_unchanged
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.files_unchanged
+```

docs/api/_src/pipeline_lint_tests/index.md

@@ -0,0 +1,9 @@
+# Pipline lint tests
+
+```{toctree}
+:caption: 'Tests:'
+:glob: true
+:maxdepth: 2
+
+*
+```

docs/api/_src/pipeline_lint_tests/merge_markers.rst → docs/api/_src/pipeline_lint_tests/merge_markers.md

@@ -1,4 +1,5 @@
-merge_markers
-==============
+# merge_markers
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.merge_markers
+```

docs/api/_src/pipeline_lint_tests/modules_json.rst → docs/api/_src/pipeline_lint_tests/modules_json.md

@@ -1,4 +1,5 @@
-nextflow_config
-===============
+# nextflow_config
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.modules_json
+```

docs/api/_src/pipeline_lint_tests/nextflow_config.rst → docs/api/_src/pipeline_lint_tests/nextflow_config.md

@@ -1,4 +1,5 @@
-nextflow_config
-===============
+# nextflow_config
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.nextflow_config
+```

docs/api/_src/pipeline_lint_tests/pipeline_name_conventions.rst → docs/api/_src/pipeline_lint_tests/pipeline_name_conventions.md

@@ -1,4 +1,5 @@
-pipeline_name_conventions
-=========================
+# pipeline_name_conventions
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.pipeline_name_conventions
+```

docs/api/_src/pipeline_lint_tests/pipeline_todos.rst → docs/api/_src/pipeline_lint_tests/pipeline_todos.md

@@ -1,4 +1,5 @@
-pipeline_todos
-==============
+# pipeline_todos
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.pipeline_todos
+```

docs/api/_src/pipeline_lint_tests/readme.rst → docs/api/_src/pipeline_lint_tests/readme.md

@@ -1,4 +1,5 @@
-readme
-======
+# readme
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.readme
+```

docs/api/_src/pipeline_lint_tests/schema_description.rst → docs/api/_src/pipeline_lint_tests/schema_description.md

@@ -1,4 +1,5 @@
-schema_description
-===========
+# schema_description
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.schema_description
+```

docs/api/_src/pipeline_lint_tests/schema_lint.rst → docs/api/_src/pipeline_lint_tests/schema_lint.md

@@ -1,4 +1,5 @@
-schema_lint
-===========
+# schema_lint
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.schema_lint
+```

docs/api/_src/pipeline_lint_tests/schema_params.rst → docs/api/_src/pipeline_lint_tests/schema_params.md

@@ -1,4 +1,5 @@
-schema_params
-=============
+# schema_params
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.schema_params
+```

docs/api/_src/pipeline_lint_tests/template_strings.rst → docs/api/_src/pipeline_lint_tests/template_strings.md

@@ -1,4 +1,5 @@
-template_strings
-================
+# template_strings
 
+```{eval-rst}
 .. automethod:: nf_core.lint.PipelineLint.template_strings
+```