feat: Autogeneration api documentation files for mkdocs (#311)

conda/dev.yaml

@@ -12,4 +12,4 @@ dependencies:
   - pip
   - pip:
       - makim==1.15.1
-      - paginate
+      - paginate==0.5.6

src/scicookie/hooks/post_gen_project.py

@@ -103,11 +103,17 @@ def remove_dirs(dirs: list):
 
 def remove_dir(dir_path):
     """Remove a directory located at PROJECT_DIRECTORY/dir_path"""
-    shutil.rmtree(PROJECT_DIRECTORY/dir_path)
+    try:
+        shutil.rmtree(PROJECT_DIRECTORY / dir_path)
+    except Exception as e:
+        print(f"Error removing directory {PROJECT_DIRECTORY / dir_path}: {e}")
 
 
 def remove_project_file(filepath: str):
-    os.remove(PROJECT_DIRECTORY / filepath)
+    try:
+        os.remove(PROJECT_DIRECTORY / filepath)
+    except Exception as e:
+        print(f"Error removing file {PROJECT_DIRECTORY / filepath}: {e}")
 
 
 def remove_package_file(filepath: str):
@@ -119,17 +125,23 @@ def move_selected_doc_dir():
         docs_target_dir = PROJECT_DIRECTORY
     else:
         docs_target_dir = PROJECT_DIRECTORY / "docs"
+        remove_dir("scripts")
 
     if DOCUMENTATION_ENGINE.startswith("sphinx"):
         DOCS_SPHINX = Path(DOCS_SPEC_DIR).parent
-        remove_dir(Path("docs") / "api")
         remove_project_file(Path("docs") / "index.md")
-        shutil.move(DOCS_SPHINX / 'conf.py', docs_target_dir)
-        shutil.move(DOCS_SPHINX / 'make.bat', docs_target_dir)
-        shutil.move(DOCS_SPHINX / 'readme.md', docs_target_dir)
+
+        for file_name in ['conf.py', 'make.bat', 'readme.md']:
+            try:
+                shutil.move(DOCS_SPHINX / file_name, docs_target_dir)
+            except Exception as e:
+                print(f"Error moving file {file_name}: {e}")
 
     for file_name in os.listdir(DOCS_SPEC_DIR):
-        shutil.move(DOCS_SPEC_DIR / file_name, docs_target_dir)
+        try:
+            shutil.move(DOCS_SPEC_DIR / file_name, docs_target_dir)
+        except Exception as e:
+            print(f"Error moving file {file_name}: {e}")
 
 
 

src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-config-pyproject.toml

@@ -88,4 +88,5 @@ ignore_missing_imports = true
 warn_unused_ignores = true
 warn_redundant_casts = true
 warn_unused_configs = true
+exclude = ["scripts/"]
 {% endif -%}

src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-pyproject.toml

@@ -67,13 +67,14 @@ dev = [
   "mkdocs-jupyter >= 0.24.1",
   "mkdocs-literate-nav >= 0.6.0",
   "mkdocs-macros-plugin >= 0.7.0, < 1",
+  "mkdocstrings >= 0.21.2",
+  "mkdocstrings-python >= 1.1.2",
+  "mkdocs-gen-files >=0.5.0",
   {% if cookiecutter.mkdocs_theme == 'material' -%}
   "mkdocs-material >= 9.1.15",
   {% elif cookiecutter.mkdocs_theme == 'cinder' -%}
   "mkdocs-cinder >= 1.2.0"
-  {% endif -%}
-  "mkdocstrings >= 0.21.2",
-  "mkdocstrings-python >= 1.1.2",
+  {% endif %}
 {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
   "Sphinx >= 6.2.1",
   {%- if cookiecutter.sphinx_theme == 'readthedocs'%}

src/scicookie/{{cookiecutter.project_slug}}/build-system/poetry/pyproject.toml

@@ -105,7 +105,8 @@ mkdocs-material = ">=9.1.15"
 mkdocs-cinder = ">=1.2.0"
 {% endif -%}
 mkdocstrings = ">=0.21.2"
-mkdocstrings-python = ">=1.1.2"
+mkdocstrings-python = ">= 1.1.2"
+mkdocs-gen-files = ">=0.5.0"
 {# keep this line here #}
 {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
 Sphinx = ">=6.2.1"

src/scicookie/{{cookiecutter.project_slug}}/docs-mkdocs/mkdocs.yaml

@@ -15,7 +15,8 @@ nav:
   - Installation: installation.md
   - Changelog: changelog.md
   - Contributing: contributing.md
-  - API: ./api/references.md
+  # from gen-files
+  - API: api/
   - Notebook page: example.ipynb
 theme:
 {% if cookiecutter.mkdocs_theme == 'default' %}
@@ -45,10 +46,15 @@ theme:
 plugins:
   - search
   - macros
-  # - autorefs
+  - autorefs
   # - exclude:
   #     glob:
   #       - backends/template.md
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_nav.py
+  - literate-nav:
+      nav_file: SUMMARY.md
   - mkdocstrings:
       enable_inventory: true
       handlers:
@@ -62,51 +68,32 @@ plugins:
           import:
             - https://docs.python.org/3/objects.inv
           options:
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: list
             docstring_style: numpy
-            filters:
-              - "!^Bounds"
-              - "!^__class__"
-              - "!^_filter_with_like"
-              - "!^_find_backends"
-              - "!^_key$"
-              - "!^_literal_value_hash_key"
-              - "!^_log"
-              - "!^_nbytes"
-              - "!^_safe_name$"
-              - "!^_schema_from_csv"
-              - "!^_to_geodataframe"
-              - "!^_tuplize"
-              - "!^ast_schema"
-              - "!^backend_table_type"
-              - "!^bounds$"
-              - "!^column$"
-              - "!^compiler$"
-              - "!^context_class"
-              - "!^database_class"
-              - "!^do_connect"
-              - "!^fetch_from_cursor"
-              - "!^get_schema"
-              - "!^largest$"
-              - "!^reconnect"
-              - "!^select_builder_class"
-              - "!^select_class"
-              - "!^table_class$"
-              - "!^table_expr_class"
-              - "!^translator_class"
-              - "!^Options$"
-            show_category_heading: true
+            filters: ["!^_"]
+            heading_level: 1
+            inherited_members: true
+            merge_init_into_class: true
+            separate_signature: true
+            # show_category_heading: true
+            # show_modules: true
             show_root_full_path: false
             show_root_heading: true
-            show_root_toc_entry: true
-            show_source: false
-            show_modules: true
+            # show_root_toc_entry: true
+            show_signature_annotations: true
+            show_source: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            summary: true
   - mkdocs-jupyter:
       execute: false
       ignore:
         - "*.py"
       include_source: true
       theme: dark
-  - literate-nav
 markdown_extensions:
   - admonition
   - attr_list
@@ -122,8 +109,10 @@ markdown_extensions:
         custom_icons:
           - docs/static/icons
   - pymdownx.details
-  - pymdownx.highlight
-  - pymdownx.inlinehilite
+  - pymdownx.highlight:
+      pygments_lang_class: true 
+  - pymdownx.inlinehilite:
+      style_plain_text: python
   - pymdownx.magiclink:
       provider: github
       repo_url_shortener: true

src/scicookie/{{cookiecutter.project_slug}}/scripts/gen_ref_nav.py

@@ -0,0 +1,58 @@
+"""
+
+Generate the code reference pages and navigation.
+
+REF:
+https://github.com/mkdocstrings/mkdocstrings/blob/main/scripts/gen_ref_nav.py
+
+"""
+
+{%- if cookiecutter.use_black == "yes" %}
+  {%- set QUOTE = '"' -%}
+{%- else %}
+  {%- set QUOTE = "'" -%}
+{%- endif %}
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+mod_symbol = (
+    '<code class="doc-symbol doc-symbol-nav doc-symbol-module"></code>'
+)
+
+root = Path(__file__).parent.parent
+{% if cookiecutter.project_layout == 'src' -%}
+src = root / {{ QUOTE }}src{{ QUOTE }}
+{% else -%}
+src = root
+{% endif -%}
+
+for path in sorted(src.rglob({{ QUOTE }}*.py{{ QUOTE }})):
+    module_path = path.relative_to(src).with_suffix({{ QUOTE }}{{ QUOTE }})
+    doc_path = path.relative_to(src / {{ QUOTE }}{{ cookiecutter.package_slug }}{{ QUOTE }}).with_suffix({{ QUOTE }}.md{{ QUOTE }})
+    full_doc_path = Path({{ QUOTE }}api{{ QUOTE }}, doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == {{ QUOTE }}__init__{{ QUOTE }}:
+        parts = parts[:-1]
+        doc_path = doc_path.with_name({{ QUOTE }}index.md{{ QUOTE }})
+        full_doc_path = full_doc_path.with_name({{ QUOTE }}index.md{{ QUOTE }})
+    elif parts[-1].startswith({{ QUOTE }}_{{ QUOTE }}):
+        continue
+
+    nav_parts = [f{{ QUOTE }}{mod_symbol} {part}{{ QUOTE }} for part in parts]
+    nav[tuple(nav_parts)] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, {{ QUOTE }}w{{ QUOTE }}) as fd:
+        ident = {{ QUOTE }}.{{ QUOTE }}.join(parts)
+        fd.write(f{{ QUOTE }}::: {ident}{{ QUOTE }})
+
+    mkdocs_gen_files.set_edit_path(
+        full_doc_path, {{ QUOTE }}..{{ QUOTE }} / path.relative_to(root)
+    )
+
+with mkdocs_gen_files.open({{ QUOTE }}api/SUMMARY.md{{ QUOTE }}, {{ QUOTE }}w{{ QUOTE }}) as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

src/scicookie/{{cookiecutter.project_slug}}/virtualenvs/conda/dev.yaml

@@ -38,3 +38,8 @@ dependencies:
 {%- if cookiecutter.use_make == "yes" %}
   - make
 {%- endif %}
+{%- if cookiecutter.build_system == "poetry" and cookiecutter.documentation_engine == "mkdocs" %}
+  - pip:
+      # distlib issue
+      - paginate==0.5.6
+ {%- endif %}