initial version for auto generation api

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

@@ -72,8 +72,8 @@ dev = [
   {% elif cookiecutter.mkdocs_theme == 'cinder' -%}
   "mkdocs-cinder >= 1.2.0"
   {% endif -%}
-  "mkdocstrings >= 0.21.2",
-  "mkdocstrings-python >= 1.1.2",
+  "mkdocstrings >=0.24.3", extras=["python"],
+  "mkdocs-gen-files >=0.5.0"
 {%- elif cookiecutter.documentation_engine.startswith("sphinx") %}
   "Sphinx >= 6.2.1",
   {%- if cookiecutter.sphinx_theme == 'readthedocs'%}

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

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

@@ -5,6 +5,8 @@ channels:
 dependencies:
   - python >=3.8.1,<4
   - pip
+  - pip:
+      - paginate
 {%- if cookiecutter.build_system == "poetry" %}
   - poetry
 {%- elif cookiecutter.build_system == "flit" %}