From 068e24ae5a8bffab4820773787eeb99b3475ba1b Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 13:05:18 +0100
Subject: [PATCH 01/20] add working generate-api-doc.sh script

---
 docs/api/generate-api-docs.sh   | 75 +++++++++++++++++++++++++++++++++
 nf_core/lint/multiqc_config.py  |  1 +
 nf_core/lint/nextflow_config.py |  1 +
 3 files changed, 77 insertions(+)
 create mode 100644 docs/api/generate-api-docs.sh

diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
new file mode 100644
index 0000000000..2d68b21204
--- /dev/null
+++ b/docs/api/generate-api-docs.sh
@@ -0,0 +1,75 @@
+#!/bin/bash
+# Set the output directory
+output_dir="${HOME}/nf-core.astro/src/content/tools/docs"
+
+# allow --force option and also a --release option (which takes a release name, or "all")
+while [ "$1" != "" ]; do
+    case $1 in
+        -f | --force )          force=true
+                                ;;
+        -r | --release )        shift
+                                releases=$1
+                                ;;
+        * )                     echo "Invalid argument: $1"
+                                exit 1
+    esac
+    shift
+done
+
+# if no release is specified, use all releases
+if [ -z "$releases" ]; then
+    releases=$(git tag)
+    # add 'dev' to the list of releases
+    releases="$releases dev"
+fi
+
+# Loop through each release
+for release in $releases
+do
+    # Checkout the release
+    git checkout "$release"
+    echo "_________________________"
+    echo "Generating docs for release: $release"
+    echo "_________________________"
+    git checkout docs/api
+    pip install -r docs/api/requirements.txt --quiet
+    # add the napoleon extension to the sphinx conf.py
+    gsed -i 's/^extensions = \[/extensions = \[\n    "sphinx_markdown_builder",/' docs/api/_src/conf.py
+
+    find nf_core -name "*.py" | while IFS= read -r file; do
+        # echo "Processing $file"
+
+        # replace ..tip:: with note in the python docstrings due to missing directive in the markdown builder
+        gsed -i 's/^\(\s*\)\.\. tip::/\1\.\. note::/g' $file
+
+    done
+
+    # fix syntax in lint/merge_markers.py
+    gsed -i 's/>>>>>>> or <<<<<<</``>>>>>>>`` or ``<<<<<<<``/g' nf_core/lint/merge_markers.py
+    # remove markdown files if --force is set
+    if [ "$force" = true ]; then
+        echo -e "\n\e[31mRemoving $output_dir/$release because of '--force'\e[0m"
+        rm -rf "$output_dir/$release"
+    fi
+    sphinx-build -b markdown docs/api/_src "$output_dir/$release"
+    # replace :::{seealso} with :::tip in the markdown files
+    find "$output_dir/$release" -name "*.md" -exec gsed -i 's/:::{seealso}/:::tip/g' {} \;
+    i=1
+    sp="/-\|" # spinner
+    find "$output_dir/$release" -name "*.md" | while IFS= read -r file; do
+        # echo "Processing $file"
+        printf "\b${sp:i++%${#sp}:1}"
+        node remark.mjs $file
+    done
+    # remove empty files
+    find "$output_dir/$release" -name "*.md" -size 0 -delete
+    # remove `.doctrees` directory
+    rm -rf "$output_dir/$release/.doctrees"
+    # run pre-commit to fix any formatting issues on the generated markdown files
+    pre-commit run --files "$output_dir/$release"
+    # undo all changes
+    git restore .
+    # lazydocs --output-path  "$output_dir/$release" \
+    #     --src-base-url="https://github.com/nf-core/tools/blob/$release/" \
+    #     --overview-file="index.md" nf_core
+done
diff --git a/nf_core/lint/multiqc_config.py b/nf_core/lint/multiqc_config.py
index 2ad786690d..9b9c80c44e 100644
--- a/nf_core/lint/multiqc_config.py
+++ b/nf_core/lint/multiqc_config.py
@@ -22,6 +22,7 @@ def multiqc_config(self) -> Dict[str, List[str]]:
         export_plots: true
 
     """
+
     passed: List[str] = []
     failed: List[str] = []
 
diff --git a/nf_core/lint/nextflow_config.py b/nf_core/lint/nextflow_config.py
index 68750cd859..d3e29d2363 100644
--- a/nf_core/lint/nextflow_config.py
+++ b/nf_core/lint/nextflow_config.py
@@ -129,6 +129,7 @@ def nextflow_config(self):
                         - config_defaults:
                             - params.input
     """
+
     passed = []
     warned = []
     failed = []

From 8b612074e4ff5d3f838787ec8376dbc6b7e37065 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 14:11:54 +0100
Subject: [PATCH 02/20] optimize script

---
 docs/api/generate-api-docs.sh | 47 +++++++++++++++++++----------------
 nf_core/lint/__init__.py      | 14 +++++------
 2 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
index 2d68b21204..73121966b9 100644
--- a/docs/api/generate-api-docs.sh
+++ b/docs/api/generate-api-docs.sh
@@ -3,29 +3,35 @@
 output_dir="${HOME}/nf-core.astro/src/content/tools/docs"
 
 # allow --force option and also a --release option (which takes a release name, or "all")
-while [ "$1" != "" ]; do
+force=false
+releases=()
+
+while [[ $# -gt 0 ]]; do
     case $1 in
-        -f | --force )          force=true
-                                ;;
-        -r | --release )        shift
-                                releases=$1
-                                ;;
-        * )                     echo "Invalid argument: $1"
-                                exit 1
+        -f | --force )
+            force=true
+            ;;
+        -r | --release )
+            shift
+            releases+=("$1")
+            ;;
+        * )
+            echo "Invalid argument: $1"
+            exit 1
+            ;;
     esac
     shift
 done
 
 # if no release is specified, use all releases
-if [ -z "$releases" ]; then
-    releases=$(git tag)
+if [[ ${#releases[@]} -eq 0 ]]; then
+    releases=($(git tag))
     # add 'dev' to the list of releases
-    releases="$releases dev"
+    releases+=("dev")
 fi
 
 # Loop through each release
-for release in $releases
-do
+for release in "${releases[@]}"; do
     # Checkout the release
     git checkout "$release"
     echo "_________________________"
@@ -34,32 +40,32 @@ do
     git checkout docs/api
     pip install -r docs/api/requirements.txt --quiet
     # add the napoleon extension to the sphinx conf.py
-    gsed -i 's/^extensions = \[/extensions = \[\n    "sphinx_markdown_builder",/' docs/api/_src/conf.py
+    sed -i 's/^extensions = \[/extensions = \[\n    "sphinx_markdown_builder",/' docs/api/_src/conf.py
 
     find nf_core -name "*.py" | while IFS= read -r file; do
         # echo "Processing $file"
 
         # replace ..tip:: with note in the python docstrings due to missing directive in the markdown builder
-        gsed -i 's/^\(\s*\)\.\. tip::/\1\.\. note::/g' $file
+        sed -i 's/^\(\s*\)\.\. tip::/\1\.\. note::/g' "$file"
 
     done
 
     # fix syntax in lint/merge_markers.py
-    gsed -i 's/>>>>>>> or <<<<<<</``>>>>>>>`` or ``<<<<<<<``/g' nf_core/lint/merge_markers.py
+    sed -i 's/>>>>>>> or <<<<<<</``>>>>>>>`` or ``<<<<<<<``/g' nf_core/lint/merge_markers.py
     # remove markdown files if --force is set
-    if [ "$force" = true ]; then
+    if [[ "$force" = true ]]; then
         echo -e "\n\e[31mRemoving $output_dir/$release because of '--force'\e[0m"
         rm -rf "$output_dir/$release"
     fi
     sphinx-build -b markdown docs/api/_src "$output_dir/$release"
     # replace :::{seealso} with :::tip in the markdown files
-    find "$output_dir/$release" -name "*.md" -exec gsed -i 's/:::{seealso}/:::tip/g' {} \;
+    find "$output_dir/$release" -name "*.md" -exec sed -i 's/:::{seealso}/:::tip/g' {} \;
     i=1
     sp="/-\|" # spinner
     find "$output_dir/$release" -name "*.md" | while IFS= read -r file; do
         # echo "Processing $file"
         printf "\b${sp:i++%${#sp}:1}"
-        node remark.mjs $file
+        node remark.mjs "$file"
     done
     # remove empty files
     find "$output_dir/$release" -name "*.md" -size 0 -delete
@@ -69,7 +75,4 @@ do
     pre-commit run --files "$output_dir/$release"
     # undo all changes
     git restore .
-    # lazydocs --output-path  "$output_dir/$release" \
-    #     --src-base-url="https://github.com/nf-core/tools/blob/$release/" \
-    #     --overview-file="index.md" nf_core
 done
diff --git a/nf_core/lint/__init__.py b/nf_core/lint/__init__.py
index d39ce5d7e9..be9ac183a6 100644
--- a/nf_core/lint/__init__.py
+++ b/nf_core/lint/__init__.py
@@ -404,9 +404,7 @@ def format_result(test_results):
             if "dev" in __version__:
                 tools_version = "latest"
             for eid, msg in test_results:
-                yield Markdown(
-                    f"[{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}.html): {msg}"
-                )
+                yield Markdown(f"[{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}): {msg}")
 
         # Table of passed tests
         if len(self.passed) > 0 and show_passed:
@@ -507,7 +505,7 @@ def _get_results_md(self):
             test_failures = "### :x: Test failures:\n\n{}\n\n".format(
                 "\n".join(
                     [
-                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}.html) - "
+                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}) - "
                         f"{strip_ansi_codes(msg, '`')}"
                         for eid, msg in self.failed
                     ]
@@ -521,7 +519,7 @@ def _get_results_md(self):
             test_ignored = "### :grey_question: Tests ignored:\n\n{}\n\n".format(
                 "\n".join(
                     [
-                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}.html) - "
+                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}) - "
                         f"{strip_ansi_codes(msg, '`')}"
                         for eid, msg in self.ignored
                     ]
@@ -535,7 +533,7 @@ def _get_results_md(self):
             test_fixed = "### :grey_question: Tests fixed:\n\n{}\n\n".format(
                 "\n".join(
                     [
-                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}.html) - "
+                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}) - "
                         f"{strip_ansi_codes(msg, '`')}"
                         for eid, msg in self.fixed
                     ]
@@ -549,7 +547,7 @@ def _get_results_md(self):
             test_warnings = "### :heavy_exclamation_mark: Test warnings:\n\n{}\n\n".format(
                 "\n".join(
                     [
-                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}.html) - "
+                        f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}) - "
                         f"{strip_ansi_codes(msg, '`')}"
                         for eid, msg in self.warned
                     ]
@@ -564,7 +562,7 @@ def _get_results_md(self):
                 "\n".join(
                     [
                         (
-                            f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid}.html)"
+                            f"* [{eid}](https://nf-co.re/tools/docs/{tools_version}/pipeline_lint_tests/{eid})"
                             f" - {strip_ansi_codes(msg, '`')}"
                         )
                         for eid, msg in self.passed

From 59214f5eb04e0aea3bfb544f4365c6890c9201e9 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 15:44:39 +0100
Subject: [PATCH 03/20] merge api docs actions to one and trigger action on
 website repo

---
 .github/workflows/tools-api-docs-dev.yml     | 54 --------------------
 .github/workflows/tools-api-docs-release.yml | 48 -----------------
 .github/workflows/tools-api-docs.yml         | 41 +++++++++++++++
 docs/api/generate-api-docs.sh                |  2 +-
 4 files changed, 42 insertions(+), 103 deletions(-)
 delete mode 100644 .github/workflows/tools-api-docs-dev.yml
 delete mode 100644 .github/workflows/tools-api-docs-release.yml
 create mode 100644 .github/workflows/tools-api-docs.yml

diff --git a/.github/workflows/tools-api-docs-dev.yml b/.github/workflows/tools-api-docs-dev.yml
deleted file mode 100644
index 19a1621092..0000000000
--- a/.github/workflows/tools-api-docs-dev.yml
+++ /dev/null
@@ -1,54 +0,0 @@
-name: nf-core/tools dev API docs
-# Run on push and PR to test that docs build
-on:
-  push:
-    branches:
-      - dev
-    paths-ignore:
-      - "CHANGELOG.md"
-  pull_request:
-    paths-ignore:
-      - "CHANGELOG.md"
-  release:
-    types: [published]
-
-# Cancel if a newer run is started
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  api-docs:
-    name: Build & push Sphinx API docs
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Check out source-code repository
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
-
-      - name: Set up Python 3.11
-        uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5
-        with:
-          python-version: 3.11
-
-      - name: Install python dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -r ./docs/api/requirements.txt
-          pip install .
-
-      - name: Build HTML docs
-        run: make --directory ./docs/api html
-
-      - name: Sync dev docs
-        # Only sync with the website if it was a push from nf-core/tools dev branch
-        if: github.repository == 'nf-core/tools' && github.event_name == 'push' && github.event.ref == 'refs/heads/dev'
-        uses: SamKirkland/FTP-Deploy-Action@8a24039354ee91000cb948cb4a1dbdf1a1b94a3c # v4.3.4
-        with:
-          server: ${{ secrets.ftp_server }}
-          username: ${{ secrets.ftp_username}}
-          password: ${{ secrets.ftp_password }}
-          local-dir: "./docs/api/_build/html/"
-          server-dir: ${{ secrets.ftp_server_old_site_dir }}/dev/
-          protocol: ${{ secrets.ftp_protocol }}
-          port: ${{ secrets.ftp_port }}
diff --git a/.github/workflows/tools-api-docs-release.yml b/.github/workflows/tools-api-docs-release.yml
deleted file mode 100644
index 45ce237f13..0000000000
--- a/.github/workflows/tools-api-docs-release.yml
+++ /dev/null
@@ -1,48 +0,0 @@
-name: nf-core/tools release API docs
-on:
-  release:
-    types: [published]
-
-# Cancel if a newer run is started
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  api-docs:
-    name: Build & push Sphinx API docs
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        dir:
-          - latest
-          - ${{ github.event.release.tag_name }}
-    steps:
-      - name: Check out source-code repository
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
-
-      - name: Set up Python 3.11
-        uses: actions/setup-python@0a5c61591373683505ea898e09a3ea4f39ef2b9c # v5
-        with:
-          python-version: 3.11
-
-      - name: Install python dependencies
-        run: |
-          pip install --upgrade pip
-          pip install -r ./docs/api/requirements.txt
-          pip install .
-
-      - name: Build HTML docs
-        run: make --directory ./docs/api html
-
-      - name: Sync release docs
-        if: github.repository == 'nf-core/tools'
-        uses: SamKirkland/FTP-Deploy-Action@8a24039354ee91000cb948cb4a1dbdf1a1b94a3c # v4.3.4
-        with:
-          server: ${{ secrets.ftp_server }}
-          username: ${{ secrets.ftp_username}}
-          password: ${{ secrets.ftp_password }}
-          local-dir: "./docs/api/_build/html/"
-          server-dir: ${{ secrets.ftp_server_old_site_dir }}/${{ matrix.dir }}/
-          protocol: ${{ secrets.ftp_protocol }}
-          port: ${{ secrets.ftp_port }}
diff --git a/.github/workflows/tools-api-docs.yml b/.github/workflows/tools-api-docs.yml
new file mode 100644
index 0000000000..60045512d4
--- /dev/null
+++ b/.github/workflows/tools-api-docs.yml
@@ -0,0 +1,41 @@
+name: nf-core/tools dev API docs
+# Run on push and PR to test that docs build
+on:
+  push:
+    branches:
+      - dev
+    paths:
+      - nf_core/**/*.py
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      ref_name:
+        description: "The branch or tag to build the API docs for"
+        required: true
+        default: "dev"
+
+# Cancel if a newer run is started
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  api-docs:
+    name: trigger API docs build on website repo
+    runs-on: ubuntu-latest
+    steps:
+      - name: trigger API docs build
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.nf_core_bot_auth_token }}
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: 'nf-core',
+              repo: 'website',
+              workflow_id: 'add-tools-api-docs.yml',
+              ref: 'main'
+              inputs: {
+                "ref_name": ${{ inputs.ref_name || github.ref_name }}
+              }
+            })
diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
index 73121966b9..1c1c5650c4 100644
--- a/docs/api/generate-api-docs.sh
+++ b/docs/api/generate-api-docs.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Set the output directory
-output_dir="${HOME}/nf-core.astro/src/content/tools/docs"
+output_dir="../src/content/tools/docs"
 
 # allow --force option and also a --release option (which takes a release name, or "all")
 force=false

From 018ce822e02abee86f31b65ff379f5fbc18e7ad8 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 15:45:01 +0100
Subject: [PATCH 04/20] add missing remark script

---
 docs/api/remark.mjs | 71 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/api/remark.mjs

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
new file mode 100644
index 0000000000..d743b42314
--- /dev/null
+++ b/docs/api/remark.mjs
@@ -0,0 +1,71 @@
+import fs from "fs";
+import { remark } from "remark";
+import { visit } from "unist-util-visit";
+
+function remarkDirectives() {
+    return transformer;
+
+    function transformer(tree) {
+        visit(tree, "heading", visitor);
+        visit(tree, "link", visitor);
+    }
+
+    function visitor(node, index, parent) {
+        if (node.depth === 4) {
+            if (["note", "warning"].includes(node.children[0].value?.toLowerCase())) {
+                const type = node.children[0].value.toLowerCase();
+                parent.children.splice(index, 1);
+                parent.children[index].children[0].value = `:::${type}\n${parent.children[index].children[0].value}`;
+                // if second to list parent.children[index].children ends with ":", check if the next node is a code block, if so, add the code block as a child to the current node
+                if (parent.children[index].children.slice(-1)[0]?.value?.trim().endsWith(":")) {
+                    if (parent.children[index + 1].type === "code") {
+                        parent.children[index].children.slice(-1)[0].value += "\n";
+                        parent.children[index].children.push(parent.children[index + 1]);
+                        parent.children.splice(index + 1, 1);
+                    }
+                }
+                parent.children[index].children.push({ type: "text", value: "\n:::" });
+            } else if (node.children[0].type !== "inlineCode") {
+                node.children[0] = {
+                    type: "inlineCode",
+                    value: node.children[0].value?.trim() + "{:python}",
+                };
+            }
+        } else if (node.depth === 3) {
+            node.children.map((child) => {
+                if (child.type === "text") {
+                    child.type = "inlineCode";
+                    child.value = child.value?.trim() + "{:python}";
+                }
+                if (child.type === "link") {
+                    child.children.map((child) => {
+                        if (child.type === "text") {
+                            child.type = "inlineCode";
+                            child.value = child.value?.trim() + "{:python}";
+                        }
+                    });
+                }
+                if (child.type === "emphasis") {
+                    child.children.map((child) => {
+                        if (child.type === "text") {
+                            child.type = "inlineCode";
+                            child.value = child.value?.trim() + "{:python}";
+                        }
+                    });
+                }
+            });
+        }
+        if (node.type === "link") {
+            node.url = node.url.replace(".md", "");
+        }
+    }
+}
+
+let markdown = fs.readFileSync(process.argv[2]);
+
+remark()
+    .use(remarkDirectives)
+    .process(markdown, function (err, file) {
+        if (err) throw err;
+        fs.writeFileSync(process.argv[2], String(file));
+    });

From 3ef89908cad272f4e0ecc31169b3e12f329980db Mon Sep 17 00:00:00 2001
From: nf-core-bot <core@nf-co.re>
Date: Thu, 15 Feb 2024 14:47:19 +0000
Subject: [PATCH 05/20] [automated] Update CHANGELOG.md

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bfa62cacf3..e28ef9404e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@
 
 - make creat-lint-wf composable ([#2733](https://github.com/nf-core/tools/pull/2733))
 - add looser comparison when pipeline logos ([#2744](https://github.com/nf-core/tools/pull/2744))
+- Switch to markdown based API and error docs ([#2758](https://github.com/nf-core/tools/pull/2758))
 
 ### Modules
 

From 5543bc4e019f7176ee64f8f6a0aa8a892e50824b Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 15:57:11 +0100
Subject: [PATCH 06/20] add outdir option to generate script

---
 .../_src/module_lint_tests/environment_yml.md   |  5 +++++
 docs/api/generate-api-docs.sh                   | 17 +++++++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100644 docs/api/_src/module_lint_tests/environment_yml.md

diff --git a/docs/api/_src/module_lint_tests/environment_yml.md b/docs/api/_src/module_lint_tests/environment_yml.md
new file mode 100644
index 0000000000..e931f9df05
--- /dev/null
+++ b/docs/api/_src/module_lint_tests/environment_yml.md
@@ -0,0 +1,5 @@
+# environment_yml
+
+```{eval-rst}
+.. automethod:: nf_core.modules.lint.ModuleLint.environment_yml
+```
diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
index 1c1c5650c4..30208bc9b3 100644
--- a/docs/api/generate-api-docs.sh
+++ b/docs/api/generate-api-docs.sh
@@ -1,6 +1,4 @@
 #!/bin/bash
-# Set the output directory
-output_dir="../src/content/tools/docs"
 
 # allow --force option and also a --release option (which takes a release name, or "all")
 force=false
@@ -15,6 +13,10 @@ while [[ $# -gt 0 ]]; do
             shift
             releases+=("$1")
             ;;
+        -o | --output )
+            shift
+            output_dir="$1"
+            ;;
         * )
             echo "Invalid argument: $1"
             exit 1
@@ -23,6 +25,12 @@ while [[ $# -gt 0 ]]; do
     shift
 done
 
+
+# Set the output directory if not set
+if [[ -z "$output_dir" ]]; then
+    output_dir="../src/content/tools/docs"
+fi
+
 # if no release is specified, use all releases
 if [[ ${#releases[@]} -eq 0 ]]; then
     releases=($(git tag))
@@ -42,6 +50,11 @@ for release in "${releases[@]}"; do
     # add the napoleon extension to the sphinx conf.py
     sed -i 's/^extensions = \[/extensions = \[\n    "sphinx_markdown_builder",/' docs/api/_src/conf.py
 
+    # run docs/api/make_lint_md.py if it exists
+    if [[ -f "docs/api/make_lint_md.py" ]]; then
+        python docs/api/make_lint_md.py
+    fi
+
     find nf_core -name "*.py" | while IFS= read -r file; do
         # echo "Processing $file"
 

From baef8a06bff5db6588d545d66b96ebd4f95fc69a Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 16:01:56 +0100
Subject: [PATCH 07/20] fix index pages

---
 docs/api/_src/index.md                     | 2 --
 docs/api/_src/module_lint_tests/index.md   | 3 +--
 docs/api/_src/pipeline_lint_tests/index.md | 3 +--
 3 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/docs/api/_src/index.md b/docs/api/_src/index.md
index cb455986d7..17bf2407f5 100644
--- a/docs/api/_src/index.md
+++ b/docs/api/_src/index.md
@@ -20,5 +20,3 @@ This documentation is for the `nf-core/tools` package.
 - [Module code lint tests](module_lint_tests/index.md) (run by `nf-core modules lint`)
 - [Subworkflow code lint tests](subworkflow_lint_tests/index.md) (run by `nf-core subworkflows lint`)
 - [nf-core/tools Python package API reference](api/index.md)
-- {ref}`genindex`
-- {ref}`modindex`
diff --git a/docs/api/_src/module_lint_tests/index.md b/docs/api/_src/module_lint_tests/index.md
index f889abf73c..dee84d06d8 100644
--- a/docs/api/_src/module_lint_tests/index.md
+++ b/docs/api/_src/module_lint_tests/index.md
@@ -1,9 +1,8 @@
 # Module lint tests
 
 ```{toctree}
-:caption: 'Tests:'
 :glob: true
-:maxdepth: 2
+:maxdepth: 1
 
 *
 ```
diff --git a/docs/api/_src/pipeline_lint_tests/index.md b/docs/api/_src/pipeline_lint_tests/index.md
index 0cf9bc1d21..c631610d64 100644
--- a/docs/api/_src/pipeline_lint_tests/index.md
+++ b/docs/api/_src/pipeline_lint_tests/index.md
@@ -1,9 +1,8 @@
 # Pipeline lint tests
 
 ```{toctree}
-:caption: 'Tests:'
 :glob: true
-:maxdepth: 2
+:maxdepth: 1
 
 *
 ```

From 7350e32b7cef907990c50931287a76789c4a371c Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 16:19:17 +0100
Subject: [PATCH 08/20] update path for remark script

---
 docs/api/generate-api-docs.sh | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
index 30208bc9b3..70e3994bf5 100644
--- a/docs/api/generate-api-docs.sh
+++ b/docs/api/generate-api-docs.sh
@@ -48,7 +48,7 @@ for release in "${releases[@]}"; do
     git checkout docs/api
     pip install -r docs/api/requirements.txt --quiet
     # add the napoleon extension to the sphinx conf.py
-    sed -i 's/^extensions = \[/extensions = \[\n    "sphinx_markdown_builder",/' docs/api/_src/conf.py
+    gsed -i 's/^extensions = \[/extensions = \[\n    "sphinx_markdown_builder",/' docs/api/_src/conf.py
 
     # run docs/api/make_lint_md.py if it exists
     if [[ -f "docs/api/make_lint_md.py" ]]; then
@@ -59,12 +59,12 @@ for release in "${releases[@]}"; do
         # echo "Processing $file"
 
         # replace ..tip:: with note in the python docstrings due to missing directive in the markdown builder
-        sed -i 's/^\(\s*\)\.\. tip::/\1\.\. note::/g' "$file"
+        gsed -i 's/^\(\s*\)\.\. tip::/\1\.\. note::/g' "$file"ba
 
     done
 
     # fix syntax in lint/merge_markers.py
-    sed -i 's/>>>>>>> or <<<<<<</``>>>>>>>`` or ``<<<<<<<``/g' nf_core/lint/merge_markers.py
+    gsed -i 's/>>>>>>> or <<<<<<</``>>>>>>>`` or ``<<<<<<<``/g' nf_core/lint/merge_markers.py
     # remove markdown files if --force is set
     if [[ "$force" = true ]]; then
         echo -e "\n\e[31mRemoving $output_dir/$release because of '--force'\e[0m"
@@ -78,7 +78,7 @@ for release in "${releases[@]}"; do
     find "$output_dir/$release" -name "*.md" | while IFS= read -r file; do
         # echo "Processing $file"
         printf "\b${sp:i++%${#sp}:1}"
-        node remark.mjs "$file"
+        node docs/api/remark.mjs "$file"
     done
     # remove empty files
     find "$output_dir/$release" -name "*.md" -size 0 -delete

From e275dff71019862996c7493b5d8b61b4a7304f98 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 16:21:34 +0100
Subject: [PATCH 09/20] don't update members in api docs

---
 docs/api/generate-api-docs.sh | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
index 70e3994bf5..194c2b6c5e 100644
--- a/docs/api/generate-api-docs.sh
+++ b/docs/api/generate-api-docs.sh
@@ -51,9 +51,9 @@ for release in "${releases[@]}"; do
     gsed -i 's/^extensions = \[/extensions = \[\n    "sphinx_markdown_builder",/' docs/api/_src/conf.py
 
     # run docs/api/make_lint_md.py if it exists
-    if [[ -f "docs/api/make_lint_md.py" ]]; then
-        python docs/api/make_lint_md.py
-    fi
+    # if [[ -f "docs/api/make_lint_md.py" ]]; then
+    #     python docs/api/make_lint_md.py
+    # fi
 
     find nf_core -name "*.py" | while IFS= read -r file; do
         # echo "Processing $file"

From 3711b74981ac97cdd95a191ce98e57b25480333c Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 16:22:42 +0100
Subject: [PATCH 10/20] remove typo

---
 docs/api/generate-api-docs.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
index 194c2b6c5e..0585e4c7fe 100644
--- a/docs/api/generate-api-docs.sh
+++ b/docs/api/generate-api-docs.sh
@@ -59,7 +59,7 @@ for release in "${releases[@]}"; do
         # echo "Processing $file"
 
         # replace ..tip:: with note in the python docstrings due to missing directive in the markdown builder
-        gsed -i 's/^\(\s*\)\.\. tip::/\1\.\. note::/g' "$file"ba
+        gsed -i 's/^\(\s*\)\.\. tip::/\1\.\. note::/g' "$file"
 
     done
 

From 4186bcbd9e473f4baae8498af2c4e09593443707 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 16:27:51 +0100
Subject: [PATCH 11/20] just copy files over and then go back to current branch

---
 docs/api/generate-api-docs.sh | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/api/generate-api-docs.sh b/docs/api/generate-api-docs.sh
index 0585e4c7fe..f30c7f0665 100644
--- a/docs/api/generate-api-docs.sh
+++ b/docs/api/generate-api-docs.sh
@@ -71,8 +71,13 @@ for release in "${releases[@]}"; do
         rm -rf "$output_dir/$release"
     fi
     sphinx-build -b markdown docs/api/_src "$output_dir/$release"
+
+    # undo all changes
+    git restore .
+
+    git checkout -
     # replace :::{seealso} with :::tip in the markdown files
-    find "$output_dir/$release" -name "*.md" -exec sed -i 's/:::{seealso}/:::tip/g' {} \;
+    find "$output_dir/$release" -name "*.md" -exec gsed -i 's/:::{seealso}/:::tip/g' {} \;
     i=1
     sp="/-\|" # spinner
     find "$output_dir/$release" -name "*.md" | while IFS= read -r file; do
@@ -86,6 +91,4 @@ for release in "${releases[@]}"; do
     rm -rf "$output_dir/$release/.doctrees"
     # run pre-commit to fix any formatting issues on the generated markdown files
     pre-commit run --files "$output_dir/$release"
-    # undo all changes
-    git restore .
 done

From 808dc688fc17602fa6d80e357bdcdebefcd17624 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:10:27 +0100
Subject: [PATCH 12/20] fix for lower level emphasis terms

---
 docs/api/remark.mjs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
index d743b42314..93192c786c 100644
--- a/docs/api/remark.mjs
+++ b/docs/api/remark.mjs
@@ -30,6 +30,13 @@ function remarkDirectives() {
                     type: "inlineCode",
                     value: node.children[0].value?.trim() + "{:python}",
                 };
+            } else if (node.children[0].type === "emphasis") {
+                child.children.map((child) => {
+                    if (child.type === "text") {
+                        child.type = "inlineCode";
+                        child.value = child.value?.trim() + "{:python}";
+                    }
+                });
             }
         } else if (node.depth === 3) {
             node.children.map((child) => {

From afa0cf06e54358500b5a1b4b0e0f4c5599da0281 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:13:26 +0100
Subject: [PATCH 13/20] add debugging

---
 docs/api/remark.mjs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
index 93192c786c..998232f12d 100644
--- a/docs/api/remark.mjs
+++ b/docs/api/remark.mjs
@@ -31,6 +31,7 @@ function remarkDirectives() {
                     value: node.children[0].value?.trim() + "{:python}",
                 };
             } else if (node.children[0].type === "emphasis") {
+                console.log(node.children);
                 child.children.map((child) => {
                     if (child.type === "text") {
                         child.type = "inlineCode";

From c0b6e19282c3cb3beac0f751bab1d3bdb2fa6234 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:15:12 +0100
Subject: [PATCH 14/20] handle emphasis before the rest

---
 docs/api/remark.mjs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
index 998232f12d..eef3b683b1 100644
--- a/docs/api/remark.mjs
+++ b/docs/api/remark.mjs
@@ -25,19 +25,19 @@ function remarkDirectives() {
                     }
                 }
                 parent.children[index].children.push({ type: "text", value: "\n:::" });
-            } else if (node.children[0].type !== "inlineCode") {
-                node.children[0] = {
-                    type: "inlineCode",
-                    value: node.children[0].value?.trim() + "{:python}",
-                };
             } else if (node.children[0].type === "emphasis") {
                 console.log(node.children);
-                child.children.map((child) => {
+                node.children[0].children.map((child) => {
                     if (child.type === "text") {
                         child.type = "inlineCode";
                         child.value = child.value?.trim() + "{:python}";
                     }
                 });
+            } else if (node.children[0].type !== "inlineCode") {
+                node.children[0] = {
+                    type: "inlineCode",
+                    value: node.children[0].value?.trim() + "{:python}",
+                };
             }
         } else if (node.depth === 3) {
             node.children.map((child) => {

From 8f40d4acf9c43938ad799051b58b82697ce0bc2b Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:16:08 +0100
Subject: [PATCH 15/20] remove debugging

---
 docs/api/remark.mjs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
index eef3b683b1..02fa6b6846 100644
--- a/docs/api/remark.mjs
+++ b/docs/api/remark.mjs
@@ -26,7 +26,6 @@ function remarkDirectives() {
                 }
                 parent.children[index].children.push({ type: "text", value: "\n:::" });
             } else if (node.children[0].type === "emphasis") {
-                console.log(node.children);
                 node.children[0].children.map((child) => {
                     if (child.type === "text") {
                         child.type = "inlineCode";

From 0f33118b16faed913426710ee3c6e40b8e813b3f Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:23:54 +0100
Subject: [PATCH 16/20] convert the whole heading to code

---
 docs/api/remark.mjs | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
index 02fa6b6846..9274321de6 100644
--- a/docs/api/remark.mjs
+++ b/docs/api/remark.mjs
@@ -32,6 +32,21 @@ function remarkDirectives() {
                         child.value = child.value?.trim() + "{:python}";
                     }
                 });
+                // convert the rest of the heading to inline code
+                node.children.slice(1).map((child) => {
+                    if (child.type === "text") {
+                        child.type = "inlineCode";
+                        child.value = child.value?.trim() + "{:python}";
+                    }
+                    if (child.type === "link") {
+                        child.children.map((child) => {
+                            if (child.type === "text") {
+                                child.type = "inlineCode";
+                                child.value = child.value?.trim() + "{:python}";
+                            }
+                        });
+                    }
+                });
             } else if (node.children[0].type !== "inlineCode") {
                 node.children[0] = {
                     type: "inlineCode",

From 714a1aab7da2fbbe5eb070c9e50e7d54d0448e77 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:29:02 +0100
Subject: [PATCH 17/20] tidy up remark code

---
 docs/api/remark.mjs | 121 +++++++++++++++++++++++---------------------
 1 file changed, 62 insertions(+), 59 deletions(-)

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
index 9274321de6..77c7a035d3 100644
--- a/docs/api/remark.mjs
+++ b/docs/api/remark.mjs
@@ -2,7 +2,7 @@ import fs from "fs";
 import { remark } from "remark";
 import { visit } from "unist-util-visit";
 
-function remarkDirectives() {
+const remarkDirectives = () => {
     return transformer;
 
     function transformer(tree) {
@@ -12,66 +12,23 @@ function remarkDirectives() {
 
     function visitor(node, index, parent) {
         if (node.depth === 4) {
-            if (["note", "warning"].includes(node.children[0].value?.toLowerCase())) {
-                const type = node.children[0].value.toLowerCase();
-                parent.children.splice(index, 1);
-                parent.children[index].children[0].value = `:::${type}\n${parent.children[index].children[0].value}`;
-                // if second to list parent.children[index].children ends with ":", check if the next node is a code block, if so, add the code block as a child to the current node
-                if (parent.children[index].children.slice(-1)[0]?.value?.trim().endsWith(":")) {
-                    if (parent.children[index + 1].type === "code") {
-                        parent.children[index].children.slice(-1)[0].value += "\n";
-                        parent.children[index].children.push(parent.children[index + 1]);
-                        parent.children.splice(index + 1, 1);
-                    }
-                }
-                parent.children[index].children.push({ type: "text", value: "\n:::" });
-            } else if (node.children[0].type === "emphasis") {
-                node.children[0].children.map((child) => {
-                    if (child.type === "text") {
-                        child.type = "inlineCode";
-                        child.value = child.value?.trim() + "{:python}";
-                    }
-                });
-                // convert the rest of the heading to inline code
-                node.children.slice(1).map((child) => {
-                    if (child.type === "text") {
-                        child.type = "inlineCode";
-                        child.value = child.value?.trim() + "{:python}";
-                    }
-                    if (child.type === "link") {
-                        child.children.map((child) => {
-                            if (child.type === "text") {
-                                child.type = "inlineCode";
-                                child.value = child.value?.trim() + "{:python}";
-                            }
-                        });
-                    }
-                });
-            } else if (node.children[0].type !== "inlineCode") {
-                node.children[0] = {
-                    type: "inlineCode",
-                    value: node.children[0].value?.trim() + "{:python}",
-                };
+            const firstChild = node.children[0];
+            if (["note", "warning"].includes(firstChild?.value?.toLowerCase())) {
+                handleNoteOrWarning(node, index, parent, firstChild);
+            } else if (firstChild?.type === "emphasis") {
+                handleEmphasis(node, firstChild);
+            } else if (firstChild?.type !== "inlineCode") {
+                handleInlineCode(node, firstChild);
             }
         } else if (node.depth === 3) {
-            node.children.map((child) => {
-                if (child.type === "text") {
-                    child.type = "inlineCode";
-                    child.value = child.value?.trim() + "{:python}";
+            node.children.forEach((child) => {
+                if (child.type === "text" || child.type === "emphasis") {
+                    handleInlineCode(node, child);
                 }
                 if (child.type === "link") {
-                    child.children.map((child) => {
-                        if (child.type === "text") {
-                            child.type = "inlineCode";
-                            child.value = child.value?.trim() + "{:python}";
-                        }
-                    });
-                }
-                if (child.type === "emphasis") {
-                    child.children.map((child) => {
+                    child.children.forEach((child) => {
                         if (child.type === "text") {
-                            child.type = "inlineCode";
-                            child.value = child.value?.trim() + "{:python}";
+                            handleInlineCode(node, child);
                         }
                     });
                 }
@@ -81,13 +38,59 @@ function remarkDirectives() {
             node.url = node.url.replace(".md", "");
         }
     }
-}
 
-let markdown = fs.readFileSync(process.argv[2]);
+    function handleNoteOrWarning(node, index, parent, firstChild) {
+        const type = firstChild.value.toLowerCase();
+        parent.children.splice(index, 1);
+        parent.children[index].children[0].value = `:::${type}\n${parent.children[index].children[0].value}`;
+
+        const lastChildValue = parent.children[index].children.slice(-1)[0]?.value?.trim();
+        if (lastChildValue?.endsWith(":") && parent.children[index + 1]?.type === "code") {
+            parent.children[index].children.slice(-1)[0].value += "\n";
+            parent.children[index].children.push(parent.children[index + 1]);
+            parent.children.splice(index + 1, 1);
+        }
+
+        parent.children[index].children.push({ type: "text", value: "\n:::" });
+    }
+
+    function handleEmphasis(node, firstChild) {
+        firstChild.children.forEach((child) => {
+            if (child.type === "text") {
+                child.type = "inlineCode";
+                child.value = `${child.value?.trim()}{:python}`;
+            }
+        });
+
+        node.children.slice(1).forEach((child) => {
+            if (child.type === "text") {
+                child.type = "inlineCode";
+                child.value = `${child.value?.trim()}{:python}`;
+            }
+            if (child.type === "link") {
+                child.children.forEach((child) => {
+                    if (child.type === "text") {
+                        child.type = "inlineCode";
+                        child.value = `${child.value?.trim()}{:python}`;
+                    }
+                });
+            }
+        });
+    }
+
+    function handleInlineCode(node, firstChild) {
+        node.children[0] = {
+            type: "inlineCode",
+            value: `${firstChild.value?.trim()}{:python}`,
+        };
+    }
+};
+
+const markdown = fs.readFileSync(process.argv[2]);
 
 remark()
     .use(remarkDirectives)
-    .process(markdown, function (err, file) {
+    .process(markdown, (err, file) => {
         if (err) throw err;
         fs.writeFileSync(process.argv[2], String(file));
     });

From 5dd018d66ecb1c8881b0059be9e638bc2ea168c8 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:29:51 +0100
Subject: [PATCH 18/20] fix one more index page

---
 docs/api/_src/subworkflow_lint_tests/index.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/api/_src/subworkflow_lint_tests/index.md b/docs/api/_src/subworkflow_lint_tests/index.md
index 6eed715c52..0ecf590c0d 100644
--- a/docs/api/_src/subworkflow_lint_tests/index.md
+++ b/docs/api/_src/subworkflow_lint_tests/index.md
@@ -1,9 +1,8 @@
 # Subworkflow lint tests
 
 ```{toctree}
-:caption: 'Tests:'
 :glob: true
-:maxdepth: 2
+:maxdepth: 1
 
 *
 ```

From fac45e72258199c4a52fc25e187cdffd7b549fa2 Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Thu, 15 Feb 2024 17:35:27 +0100
Subject: [PATCH 19/20] use different remark logic

---
 docs/api/remark.mjs | 121 +++++++++++++++++++++-----------------------
 1 file changed, 59 insertions(+), 62 deletions(-)

diff --git a/docs/api/remark.mjs b/docs/api/remark.mjs
index 77c7a035d3..9274321de6 100644
--- a/docs/api/remark.mjs
+++ b/docs/api/remark.mjs
@@ -2,7 +2,7 @@ import fs from "fs";
 import { remark } from "remark";
 import { visit } from "unist-util-visit";
 
-const remarkDirectives = () => {
+function remarkDirectives() {
     return transformer;
 
     function transformer(tree) {
@@ -12,23 +12,66 @@ const remarkDirectives = () => {
 
     function visitor(node, index, parent) {
         if (node.depth === 4) {
-            const firstChild = node.children[0];
-            if (["note", "warning"].includes(firstChild?.value?.toLowerCase())) {
-                handleNoteOrWarning(node, index, parent, firstChild);
-            } else if (firstChild?.type === "emphasis") {
-                handleEmphasis(node, firstChild);
-            } else if (firstChild?.type !== "inlineCode") {
-                handleInlineCode(node, firstChild);
+            if (["note", "warning"].includes(node.children[0].value?.toLowerCase())) {
+                const type = node.children[0].value.toLowerCase();
+                parent.children.splice(index, 1);
+                parent.children[index].children[0].value = `:::${type}\n${parent.children[index].children[0].value}`;
+                // if second to list parent.children[index].children ends with ":", check if the next node is a code block, if so, add the code block as a child to the current node
+                if (parent.children[index].children.slice(-1)[0]?.value?.trim().endsWith(":")) {
+                    if (parent.children[index + 1].type === "code") {
+                        parent.children[index].children.slice(-1)[0].value += "\n";
+                        parent.children[index].children.push(parent.children[index + 1]);
+                        parent.children.splice(index + 1, 1);
+                    }
+                }
+                parent.children[index].children.push({ type: "text", value: "\n:::" });
+            } else if (node.children[0].type === "emphasis") {
+                node.children[0].children.map((child) => {
+                    if (child.type === "text") {
+                        child.type = "inlineCode";
+                        child.value = child.value?.trim() + "{:python}";
+                    }
+                });
+                // convert the rest of the heading to inline code
+                node.children.slice(1).map((child) => {
+                    if (child.type === "text") {
+                        child.type = "inlineCode";
+                        child.value = child.value?.trim() + "{:python}";
+                    }
+                    if (child.type === "link") {
+                        child.children.map((child) => {
+                            if (child.type === "text") {
+                                child.type = "inlineCode";
+                                child.value = child.value?.trim() + "{:python}";
+                            }
+                        });
+                    }
+                });
+            } else if (node.children[0].type !== "inlineCode") {
+                node.children[0] = {
+                    type: "inlineCode",
+                    value: node.children[0].value?.trim() + "{:python}",
+                };
             }
         } else if (node.depth === 3) {
-            node.children.forEach((child) => {
-                if (child.type === "text" || child.type === "emphasis") {
-                    handleInlineCode(node, child);
+            node.children.map((child) => {
+                if (child.type === "text") {
+                    child.type = "inlineCode";
+                    child.value = child.value?.trim() + "{:python}";
                 }
                 if (child.type === "link") {
-                    child.children.forEach((child) => {
+                    child.children.map((child) => {
+                        if (child.type === "text") {
+                            child.type = "inlineCode";
+                            child.value = child.value?.trim() + "{:python}";
+                        }
+                    });
+                }
+                if (child.type === "emphasis") {
+                    child.children.map((child) => {
                         if (child.type === "text") {
-                            handleInlineCode(node, child);
+                            child.type = "inlineCode";
+                            child.value = child.value?.trim() + "{:python}";
                         }
                     });
                 }
@@ -38,59 +81,13 @@ const remarkDirectives = () => {
             node.url = node.url.replace(".md", "");
         }
     }
+}
 
-    function handleNoteOrWarning(node, index, parent, firstChild) {
-        const type = firstChild.value.toLowerCase();
-        parent.children.splice(index, 1);
-        parent.children[index].children[0].value = `:::${type}\n${parent.children[index].children[0].value}`;
-
-        const lastChildValue = parent.children[index].children.slice(-1)[0]?.value?.trim();
-        if (lastChildValue?.endsWith(":") && parent.children[index + 1]?.type === "code") {
-            parent.children[index].children.slice(-1)[0].value += "\n";
-            parent.children[index].children.push(parent.children[index + 1]);
-            parent.children.splice(index + 1, 1);
-        }
-
-        parent.children[index].children.push({ type: "text", value: "\n:::" });
-    }
-
-    function handleEmphasis(node, firstChild) {
-        firstChild.children.forEach((child) => {
-            if (child.type === "text") {
-                child.type = "inlineCode";
-                child.value = `${child.value?.trim()}{:python}`;
-            }
-        });
-
-        node.children.slice(1).forEach((child) => {
-            if (child.type === "text") {
-                child.type = "inlineCode";
-                child.value = `${child.value?.trim()}{:python}`;
-            }
-            if (child.type === "link") {
-                child.children.forEach((child) => {
-                    if (child.type === "text") {
-                        child.type = "inlineCode";
-                        child.value = `${child.value?.trim()}{:python}`;
-                    }
-                });
-            }
-        });
-    }
-
-    function handleInlineCode(node, firstChild) {
-        node.children[0] = {
-            type: "inlineCode",
-            value: `${firstChild.value?.trim()}{:python}`,
-        };
-    }
-};
-
-const markdown = fs.readFileSync(process.argv[2]);
+let markdown = fs.readFileSync(process.argv[2]);
 
 remark()
     .use(remarkDirectives)
-    .process(markdown, (err, file) => {
+    .process(markdown, function (err, file) {
         if (err) throw err;
         fs.writeFileSync(process.argv[2], String(file));
     });

From 2c11e4b5e752ecf33a896b2ccc8b91d540b89e1e Mon Sep 17 00:00:00 2001
From: mashehu <mashehu3@gmail.com>
Date: Fri, 16 Feb 2024 11:05:59 +0100
Subject: [PATCH 20/20] fix api index page

---
 docs/api/_src/api/index.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/api/_src/api/index.md b/docs/api/_src/api/index.md
index 9050280fd3..a1863f7e39 100644
--- a/docs/api/_src/api/index.md
+++ b/docs/api/_src/api/index.md
@@ -1,9 +1,8 @@
 # API Reference
 
 ```{toctree}
-:caption: 'Tests:'
 :glob: true
-:maxdepth: 2
+:maxdepth: 1
 
 *
 ```