Replace building of python client documentation with pydoc to mkdocst…

…rings

tools/build_documentation.sh

@@ -35,10 +35,9 @@ mkdir -p "$SCRIPT_DIR"/../website/static/html/
 
 cp -r "$AUTO_GENERATED"/rest_api_doc_spec.yaml "$SCRIPT_DIR"/../website/static/yaml/
 cp -r "$AUTO_GENERATED"/rest_api_doc.html "$SCRIPT_DIR"/../website/static/html/
-cp -r "$AUTO_GENERATED"/client_api "$DOCS"
+cp -r "$AUTO_GENERATED"/site "$SCRIPT_DIR"/../website/static/html/
 cp -r "$AUTO_GENERATED"/bin "$DOCS"
 
-
 echo "Generating Release Notes..."
 "$SCRIPT_DIR"/generate_release_notes.py
 echo "Generating Release Notes Index..."

tools/run_in_docker/generate_client_api_docs.sh

@@ -4,22 +4,11 @@ set -e
 
 echo "Generating the Client Api Docs..."
 
-pip install --upgrade "pydoc-markdown>3" &> /dev/null
+#pip install --upgrade "pydoc-markdown>3" &> /dev/null
+pip install --upgrade mkdocs mkdocs-gen-files mkdocstrings-python mkdocs-material
 
 mkdir -p /auto_generated/client_api
-for f in rucio/lib/rucio/client/*.py; do
-    if [[ $f =~ "__init__" ]]; then
-	continue
-    fi
 
-    executable_name=$(basename "$f" ".py")
+mkdocs build --clean --no-directory-urls
 
-    config="
-processors:
-  - type: rucio_processor.RucioProcessor
-renderer:
-  type: rucio_renderer.RucioRenderer"
-    content=$(PYTHONPATH=. pydoc-markdown -I rucio/lib/rucio/client -m "$executable_name" "$config")
-
-    echo "$content" > /auto_generated/client_api/"$executable_name".md
-done
+cp -r site /auto_generated/

tools/run_in_docker/generate_client_api_pages.py

@@ -0,0 +1,24 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+import os
+import mkdocs_gen_files
+
+src = Path("rucio/lib/rucio/client/")
+root = src.parent
+doc_path = "/auto_generated/client_api"
+files = os.listdir(doc_path)
+for file in files: 
+    os.remove(f"{doc_path}/{file}")
+
+
+py_files = [f for f in list(src.rglob("*.py")) if "__init__.py" not in f.name]
+
+for path in py_files:
+    module_name = path.name.split('.py')[0]
+    full_doc_path = Path(f"{doc_path}/{module_name}.md")
+
+    with mkdocs_gen_files.open(full_doc_path, "a") as fd:
+        module_path = path.relative_to(src).with_suffix("")
+        fd.write(f"::: rucio.client.{module_path}")
+        fd.write("\n\n")

tools/run_in_docker/mkdocs.yml

@@ -0,0 +1,51 @@
+site_name: "Rucio Python Client Documentation"
+repo_url: https://github.com/rucio/rucio/
+site_url: https://rucio.cern.ch/documentation/
+copyright: "Copyright © 2024 CERN"
+docs_dir: /auto_generated/client_api
+use_directory_urls: true
+not_in_nav: 
+  /auto_generated
+
+theme: 
+  name: material
+  logo: ../../img/rucio_horizontaled_black_cropped.svg
+  extra_css: ../../../src/customTheme.css
+  extra: 
+    homepage: https://rucio.cern.ch/documentation/
+  features:
+  - content.code.copy
+  - toc.follow
+  palette: 
+    - scheme: default
+      primary: white
+      toggle:
+        icon: material/brightness-7 
+        name: Switch to dark mode
+    - scheme: slate
+      primary: white
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+markdown_extensions: 
+- toc:
+    permalink: true
+plugins:
+- gen-files:
+    scripts:
+    - generate_client_api_pages.py 
+- search
+- autorefs
+- mkdocstrings:
+    default_handler: python
+    handlers:
+      python:
+        options:
+          members_order: "source"
+          heading_level: 2
+          show_source: false
+          allow_inspection: false
+          merge_init_into_class: true
+          docstring_style: "sphinx"
+          show_bases: false

website/docusaurus.config.js

@@ -54,7 +54,7 @@ module.exports={
       },
       "items": [
         {
-          "to": "client_api/accountclient",
+          "to": "pathname:///html/site/accountclient.html",
           "label": "Python Client API",
           "position": "left"
         },