Skip to content

Commit

Permalink
initial version for auto generation api
Browse files Browse the repository at this point in the history
  • Loading branch information
YurelyCamacho committed Aug 26, 2024
1 parent e0ccc0c commit a228dd2
Show file tree
Hide file tree
Showing 6 changed files with 85 additions and 45 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -88,4 +88,5 @@ ignore_missing_imports = true
warn_unused_ignores = true
warn_redundant_casts = true
warn_unused_configs = true
exclude = ["scripts/"]
{% endif -%}
Original file line number Diff line number Diff line change
Expand Up @@ -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'%}
Expand Down
69 changes: 29 additions & 40 deletions src/scicookie/{{cookiecutter.project_slug}}/docs-mkdocs/mkdocs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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' %}
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand Down

This file was deleted.

51 changes: 51 additions & 0 deletions src/scicookie/{{cookiecutter.project_slug}}/scripts/gen_ref_nav.py
Original file line number Diff line number Diff line change
@@ -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())
Original file line number Diff line number Diff line change
Expand Up @@ -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" %}
Expand Down

0 comments on commit a228dd2

Please sign in to comment.