From 23ae55b4769c0dc929edb3d30a16eb580c280716 Mon Sep 17 00:00:00 2001 From: Nicolas Date: Mon, 28 Jul 2025 16:21:16 +0200 Subject: [PATCH] doc path renamed to "api" --- .flake8 | 2 +- .github/workflows/docs.yml | 2 ++ .gitignore | 2 +- docs/source/generate_class_list.py | 10 +++++----- docs/source/index.md | 4 ++-- docs/source/render_examples.py | 4 ++-- examples/README.md | 6 +++--- 7 files changed, 16 insertions(+), 14 deletions(-) diff --git a/.flake8 b/.flake8 index f35b80a..aa1372a 100644 --- a/.flake8 +++ b/.flake8 @@ -14,7 +14,7 @@ exclude = dist, .conda, tests/autogenerated_*, - docs/source/_autogenerated + docs/source/api .venv, venv diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b188cc8..75b0258 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -41,6 +41,8 @@ jobs: rm ./source/*.rst make html touch ./build/html/.nojekyll + mkdir -p ./build/html/_autogenerated + cp ./build/html/api/* ./build/html/_autogenerated/ - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/.gitignore b/.gitignore index e6f417f..98fb789 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,7 @@ __pycache__ .pytest_cache tests/autogenerated_*.py docs/build/ -docs/source/_autogenerated/ +docs/source/api/ venv/ .venv/ thermo_data/combined_data.yaml diff --git a/docs/source/generate_class_list.py b/docs/source/generate_class_list.py index f2e48f4..839650b 100644 --- a/docs/source/generate_class_list.py +++ b/docs/source/generate_class_list.py @@ -27,7 +27,7 @@ def write_classes(f: TextIOWrapper, patterns: list[str], module_name: str, title write_dochtree(f, title, classes) for cls in classes: - with open(f'docs/source/_autogenerated/{cls}.md', 'w') as f2: + with open(f'docs/source/api/{cls}.md', 'w') as f2: f2.write(f'# {module_name}.{cls}\n') f2.write('```{eval-rst}\n') f2.write(f'.. autoclass:: {module_name}.{cls}\n') @@ -43,7 +43,7 @@ def write_functions(f: TextIOWrapper, patterns: list[str], module_name: str, tit module = importlib.import_module(module_name) functions = [ - name for name, obj in inspect.getmembers(module, inspect.isfunction) + name for name, _ in inspect.getmembers(module, inspect.isfunction) if (any(fnmatch.fnmatch(name, pat) for pat in patterns if pat not in exclude)) ] @@ -54,7 +54,7 @@ def write_functions(f: TextIOWrapper, patterns: list[str], module_name: str, tit for func in functions: if not func.startswith('_'): - with open(f'docs/source/_autogenerated/{func}.md', 'w') as f2: + with open(f'docs/source/api/{func}.md', 'w') as f2: f2.write(f'# {module_name}.{func}\n') f2.write('```{eval-rst}\n') f2.write(f'.. autofunction:: {module_name}.{func}\n') @@ -74,9 +74,9 @@ def write_dochtree(f: TextIOWrapper, title: str, items: list[str]): if __name__ == "__main__": # Ensure the output directory exists - os.makedirs('docs/source/_autogenerated', exist_ok=True) + os.makedirs('docs/source/api', exist_ok=True) - with open('docs/source/_autogenerated/index.md', 'w') as f: + with open('docs/source/api/index.md', 'w') as f: f.write('# Classes and functions\n\n') write_classes(f, ['*'], 'gaspype', title='Classes') diff --git a/docs/source/index.md b/docs/source/index.md index 9e284ef..9a995e2 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,8 +1,8 @@ ```{toctree} :maxdepth: 1 :hidden: -_autogenerated/index -_autogenerated/examples +api/index +api/examples ``` ```{include} ../../README.md diff --git a/docs/source/render_examples.py b/docs/source/render_examples.py index fc19441..90212ec 100644 --- a/docs/source/render_examples.py +++ b/docs/source/render_examples.py @@ -51,7 +51,7 @@ def render_examples(filter: str, example_file: str): f.write('## Download Jupyter Notebooks\n\n') for path, name in zip(files, names): if name.lower() != 'readme': - run_rendering(path, 'docs/source/_autogenerated') + run_rendering(path, 'docs/source/api') notebook = name + '.ipynb' f.write(f'- [{notebook}]({notebook})\n\n') @@ -63,4 +63,4 @@ def render_examples(filter: str, example_file: str): if __name__ == "__main__": - render_examples('examples/*.md', 'docs/source/_autogenerated/examples.md') + render_examples('examples/*.md', 'docs/source/api/examples.md') diff --git a/examples/README.md b/examples/README.md index ba40e2f..690d275 100644 --- a/examples/README.md +++ b/examples/README.md @@ -11,11 +11,11 @@ The conversion is done like the following automated by the [docs/source/render_examples.py](../docs/source/render_examples.py) script: ``` bash # Converting markdown with code sections to Jupyter Notebook and run it: -notedown examples/soec_methane.md --to notebook --output docs/source/_autogenerated/soec_methane.ipynb --run +notedown examples/soec_methane.md --to notebook --output docs/source/api/soec_methane.ipynb --run # Converting the Jupyter Notebook to Markdown and a folder with image -# files placed in docs/source/_autogenerated/: -jupyter nbconvert --to markdown docs/source/_autogenerated/soec_methane.ipynb --output soec_methane.md +# files placed in docs/source/api/: +jupyter nbconvert --to markdown docs/source/api/soec_methane.ipynb --output soec_methane.md ``` A new example Markdown file can be created from a Jupyter Notebook running