diff --git a/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-config-pyproject.toml b/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-config-pyproject.toml index a7a4e44a..061eeec4 100644 --- a/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-config-pyproject.toml +++ b/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 -%} diff --git a/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-pyproject.toml b/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-pyproject.toml index c257b828..98b23569 100644 --- a/src/scicookie/{{cookiecutter.project_slug}}/build-system/base/dev-deps-pyproject.toml +++ b/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'%} diff --git a/src/scicookie/{{cookiecutter.project_slug}}/docs-mkdocs/mkdocs.yaml b/src/scicookie/{{cookiecutter.project_slug}}/docs-mkdocs/mkdocs.yaml index a29a7d36..da49fa07 100644 --- a/src/scicookie/{{cookiecutter.project_slug}}/docs-mkdocs/mkdocs.yaml +++ b/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 diff --git a/src/scicookie/{{cookiecutter.project_slug}}/docs/api/references.md b/src/scicookie/{{cookiecutter.project_slug}}/docs/api/references.md deleted file mode 100644 index 96986981..00000000 --- a/src/scicookie/{{cookiecutter.project_slug}}/docs/api/references.md +++ /dev/null @@ -1,3 +0,0 @@ -# Api references - -::: {{ cookiecutter.package_slug }} diff --git a/src/scicookie/{{cookiecutter.project_slug}}/scripts/gen_ref_nav.py b/src/scicookie/{{cookiecutter.project_slug}}/scripts/gen_ref_nav.py new file mode 100644 index 00000000..07cb12f3 --- /dev/null +++ b/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 = '' + +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()) diff --git a/src/scicookie/{{cookiecutter.project_slug}}/virtualenvs/conda/dev.yaml b/src/scicookie/{{cookiecutter.project_slug}}/virtualenvs/conda/dev.yaml index 094fb412..23f2f8ad 100644 --- a/src/scicookie/{{cookiecutter.project_slug}}/virtualenvs/conda/dev.yaml +++ b/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" %}