diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml index 6ab3295b..75cf10c3 100644 --- a/.github/workflows/deploy-docs.yml +++ b/.github/workflows/deploy-docs.yml @@ -1,8 +1,5 @@ -# From https://github.com/mitmproxy/pdoc/blob/main/.github/workflows/docs.yml -# with minor adaptations - -name: Deploy docs - +# From https://github.com/mhausenblas/mkdocs-deploy-gh-pages +name: Publish mkDocs via GitHub Pages # build the documentation whenever there are new commits on main on: push: @@ -17,33 +14,17 @@ permissions: contents: read jobs: - # Build the documentation and upload the static HTML files as an artifact. build: + name: Deploy MkDocs runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 - with: - python-version: '3.10' - - - run: pip install -e .[build] - - run: pdoc -o docs-generated/ -t docs/templates --math --docformat=numpy docs/bib/bib.py docs/dev_guide.py ./dapper + - name: Checkout main + uses: actions/checkout@v2 - - uses: actions/upload-pages-artifact@v1 - with: - path: docs-generated/ - - # Deploy the artifact to GitHub pages. - # This is a separate job so that only actions/deploy-pages has the necessary permissions. - deploy: - needs: build - runs-on: ubuntu-latest - permissions: - pages: write - id-token: write - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - id: deployment - uses: actions/deploy-pages@v1 + - name: Deploy docs + uses: mhausenblas/mkdocs-deploy-gh-pages@master + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + CONFIG_FILE: mkdocs.yml + REQUIREMENTS: requirements.txt + # CUSTOM_DOMAIN: optionaldomain.com diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py new file mode 100644 index 00000000..509c3975 --- /dev/null +++ b/docs/gen_ref_pages.py @@ -0,0 +1,41 @@ +"""Generate the code reference pages.""" +# Based on https://mkdocstrings.github.io/recipes/ + +from pathlib import Path + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() + +root = Path(__file__).parent.parent +src = root / "dapper" + +for path in sorted(src.rglob("*.py")): + module_path = path.relative_to(src).with_suffix("") + doc_path = path.relative_to(src).with_suffix(".md") + full_doc_path = Path("reference", doc_path) + + parts = tuple(module_path.parts) + + if parts[-1] == "__init__": + parts = parts[:-1] or src.parts[-1:] + if not parts: + # we're in root pkg + parts = src.parts[-1:] + doc_path = doc_path.with_name("index.md") + full_doc_path = full_doc_path.with_name("index.md") + elif parts[-1] == "__main__": + continue + + # PS: rm mkdocs_gen_files to get to inspect actual .md files + # NB: will (over)write in docs/ folder. + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + identifier = ".".join(parts) + print("::: " + identifier, file=fd) + + mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root)) + +# > So basically, you can use the literate-nav plugin just for its ability to +# > infer only sub-directories, without ever writing any actual "literate navs". +# with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: +# nav_file.writelines(nav.build_literate_nav()) diff --git a/mkdocs.yml b/mkdocs.yml index ba5b131a..3b614e68 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,7 +5,7 @@ repo_url: https://github.com/nansencenter/DAPPER # edit_uri: edit/master/docs/ docs_dir: docs -watch: [mkdocs.yml, README.md, dapper, scripts/gen_ref_pages.py] +watch: [mkdocs.yml, README.md, dapper] nav: - Home: index.md - Reference: reference/ @@ -66,7 +66,7 @@ plugins: # Autodoc from docstrings: - gen-files: # Genrate .md reflecting .py hierarchy: scripts: - - scripts/gen_ref_pages.py + - docs/gen_ref_pages.py - literate-nav: # Auto-generate nav nav_file: SUMMARY.md - section-index diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..961629b2 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,610 @@ +# This file was autogenerated by uv via the following command: +# uv pip compile --extra dev setup.py -o requirements.txt +anyio==4.6.2.post1 + # via + # httpx + # jupyter-server +appnope==0.1.4 + # via ipykernel +argon2-cffi==23.1.0 + # via jupyter-server +argon2-cffi-bindings==21.2.0 + # via argon2-cffi +arrow==1.3.0 + # via isoduration +asttokens==2.4.1 + # via stack-data +async-lru==2.0.4 + # via jupyterlab +attrs==24.2.0 + # via + # jsonschema + # referencing +babel==2.16.0 + # via + # jupyterlab-server + # mkdocs-material +beautifulsoup4==4.12.3 + # via nbconvert +bleach==6.2.0 + # via nbconvert +cachetools==5.5.0 + # via tox +certifi==2024.8.30 + # via + # httpcore + # httpx + # requests +cffi==1.17.1 + # via argon2-cffi-bindings +cfgv==3.4.0 + # via pre-commit +chardet==5.2.0 + # via tox +charset-normalizer==3.4.0 + # via requests +click==8.1.7 + # via + # mkdocs + # mkdocstrings +colorama==0.4.6 + # via + # dapper (setup.py) + # griffe + # mkdocs-material + # tox +comm==0.2.2 + # via + # ipykernel + # ipywidgets +contourpy==1.3.0 + # via matplotlib +coverage==7.6.4 + # via + # dapper (setup.py) + # pytest-cov +cycler==0.12.1 + # via matplotlib +debugpy==1.8.7 + # via ipykernel +decorator==5.1.1 + # via + # ipdb + # ipython +defusedxml==0.7.1 + # via nbconvert +dill==0.3.8 + # via + # dapper (setup.py) + # multiprocess + # pathos +distlib==0.3.9 + # via virtualenv +docutils==0.21.2 + # via readme-renderer +execnet==2.1.1 + # via pytest-xdist +executing==2.1.0 + # via stack-data +fastjsonschema==2.20.0 + # via nbformat +filelock==3.16.1 + # via + # tox + # virtualenv +fonttools==4.54.1 + # via matplotlib +fqdn==1.5.1 + # via jsonschema +ghp-import==2.1.0 + # via mkdocs +griffe==1.5.1 + # via mkdocstrings-python +h11==0.14.0 + # via httpcore +httpcore==1.0.6 + # via httpx +httpx==0.27.2 + # via jupyterlab +identify==2.6.1 + # via pre-commit +idna==3.10 + # via + # anyio + # httpx + # jsonschema + # requests +importlib-metadata==8.5.0 + # via twine +iniconfig==2.0.0 + # via pytest +ipdb==0.13.13 + # via dapper (setup.py) +ipykernel==6.29.5 + # via + # jupyter + # jupyter-console + # jupyterlab + # mkdocs-jupyter +ipython==8.29.0 + # via + # dapper (setup.py) + # ipdb + # ipykernel + # ipywidgets + # jupyter-console +ipywidgets==8.1.5 + # via jupyter +isoduration==20.11.0 + # via jsonschema +jaraco-classes==3.4.0 + # via keyring +jaraco-context==6.0.1 + # via keyring +jaraco-functools==4.1.0 + # via keyring +jedi==0.19.1 + # via ipython +jinja2==3.1.4 + # via + # jupyter-server + # jupyterlab + # jupyterlab-server + # mkdocs + # mkdocs-material + # mkdocstrings + # nbconvert +json5==0.9.25 + # via jupyterlab-server +jsonpointer==3.0.0 + # via jsonschema +jsonschema==4.23.0 + # via + # jupyter-events + # jupyterlab-server + # nbformat +jsonschema-specifications==2024.10.1 + # via jsonschema +jupyter==1.1.1 + # via dapper (setup.py) +jupyter-client==8.6.3 + # via + # ipykernel + # jupyter-console + # jupyter-server + # nbclient +jupyter-console==6.6.3 + # via jupyter +jupyter-core==5.7.2 + # via + # ipykernel + # jupyter-client + # jupyter-console + # jupyter-server + # jupyterlab + # nbclient + # nbconvert + # nbformat +jupyter-events==0.10.0 + # via jupyter-server +jupyter-lsp==2.2.5 + # via jupyterlab +jupyter-server==2.14.2 + # via + # jupyter-lsp + # jupyterlab + # jupyterlab-server + # notebook + # notebook-shim +jupyter-server-terminals==0.5.3 + # via jupyter-server +jupyterlab==4.2.5 + # via + # jupyter + # notebook +jupyterlab-pygments==0.3.0 + # via nbconvert +jupyterlab-server==2.27.3 + # via + # jupyterlab + # notebook +jupyterlab-widgets==3.0.13 + # via ipywidgets +jupytext==1.16.4 + # via + # dapper (setup.py) + # mkdocs-jupyter +keyring==25.5.0 + # via twine +kiwisolver==1.4.7 + # via matplotlib +latexcodec==3.0.0 + # via pybtex +line-profiler==4.1.3 + # via dapper (setup.py) +markdown==3.7 + # via + # mkdocs + # mkdocs-autorefs + # mkdocs-material + # mkdocstrings + # pymdown-extensions +markdown-it-py==3.0.0 + # via + # jupytext + # mdit-py-plugins + # rich +markupsafe==3.0.2 + # via + # jinja2 + # mkdocs + # mkdocs-autorefs + # mkdocstrings + # nbconvert +matplotlib==3.8.4 + # via + # dapper (setup.py) + # mpl-tools + # patlib +matplotlib-inline==0.1.7 + # via + # ipykernel + # ipython +mdit-py-plugins==0.4.2 + # via jupytext +mdurl==0.1.2 + # via markdown-it-py +mergedeep==1.3.4 + # via + # mkdocs + # mkdocs-get-deps +mistune==3.0.2 + # via nbconvert +mkdocs==1.6.1 + # via + # mkdocs-autorefs + # mkdocs-gen-files + # mkdocs-jupyter + # mkdocs-literate-nav + # mkdocs-material + # mkdocs-section-index + # mkdocstrings +mkdocs-autorefs==1.2.0 + # via + # mkdocstrings + # mkdocstrings-python +mkdocs-gen-files==0.5.0 + # via dapper (setup.py) +mkdocs-get-deps==0.2.0 + # via mkdocs +mkdocs-glightbox==0.4.0 + # via dapper (setup.py) +mkdocs-jupyter==0.25.1 + # via dapper (setup.py) +mkdocs-literate-nav==0.6.1 + # via dapper (setup.py) +mkdocs-material==9.5.42 + # via + # dapper (setup.py) + # mkdocs-jupyter +mkdocs-material-extensions==1.3.1 + # via mkdocs-material +mkdocs-section-index==0.3.9 + # via dapper (setup.py) +mkdocstrings==0.26.2 + # via + # dapper (setup.py) + # mkdocstrings-python +mkdocstrings-python==1.12.2 + # via dapper (setup.py) +more-itertools==10.5.0 + # via + # jaraco-classes + # jaraco-functools +mpl-tools==0.2.50 + # via dapper (setup.py) +multiprocess==0.70.16 + # via pathos +nbclient==0.10.0 + # via nbconvert +nbconvert==7.16.4 + # via + # jupyter + # jupyter-server + # mkdocs-jupyter +nbformat==5.10.4 + # via + # jupyter-server + # jupytext + # nbclient + # nbconvert +nest-asyncio==1.6.0 + # via ipykernel +nh3==0.2.18 + # via readme-renderer +nodeenv==1.9.1 + # via pre-commit +notebook==7.2.2 + # via jupyter +notebook-shim==0.2.4 + # via + # jupyterlab + # notebook +numpy==1.26.4 + # via + # dapper (setup.py) + # contourpy + # matplotlib + # patlib + # scipy +overrides==7.7.0 + # via jupyter-server +packaging==24.1 + # via + # ipykernel + # jupyter-server + # jupyterlab + # jupyterlab-server + # jupytext + # matplotlib + # mkdocs + # nbconvert + # pyproject-api + # pytest + # pytest-sugar + # tox +paginate==0.5.7 + # via mkdocs-material +pandocfilters==1.5.1 + # via nbconvert +parso==0.8.4 + # via jedi +pathos==0.3.2 + # via dapper (setup.py) +pathspec==0.12.1 + # via mkdocs +patlib==0.3.5 + # via dapper (setup.py) +pexpect==4.9.0 + # via ipython +pillow==11.0.0 + # via matplotlib +pkginfo==1.10.0 + # via twine +platformdirs==4.3.6 + # via + # jupyter-core + # mkdocs-get-deps + # mkdocstrings + # tox + # virtualenv +pluggy==1.5.0 + # via + # pytest + # tox +pox==0.3.5 + # via pathos +ppft==1.7.6.9 + # via pathos +pprintpp==0.4.0 + # via pytest-clarity +pre-commit==4.0.1 + # via dapper (setup.py) +prometheus-client==0.21.0 + # via jupyter-server +prompt-toolkit==3.0.48 + # via + # ipython + # jupyter-console +psutil==6.1.0 + # via ipykernel +ptyprocess==0.7.0 + # via + # pexpect + # terminado +pure-eval==0.2.3 + # via stack-data +py-cpuinfo==9.0.0 + # via pytest-benchmark +pybtex==0.24.0 + # via dapper (setup.py) +pycparser==2.22 + # via cffi +pygments==2.18.0 + # via + # ipython + # jupyter-console + # mkdocs-jupyter + # mkdocs-material + # nbconvert + # readme-renderer + # rich +pymdown-extensions==10.12 + # via + # mkdocs-material + # mkdocstrings +pyparsing==3.2.0 + # via matplotlib +pyproject-api==1.8.0 + # via tox +pytest==8.3.3 + # via + # dapper (setup.py) + # pytest-benchmark + # pytest-clarity + # pytest-cov + # pytest-sugar + # pytest-timeout + # pytest-xdist +pytest-benchmark==5.1.0 + # via dapper (setup.py) +pytest-clarity==1.0.1 + # via dapper (setup.py) +pytest-cov==6.0.0 + # via dapper (setup.py) +pytest-sugar==1.0.0 + # via dapper (setup.py) +pytest-timeout==2.3.1 + # via dapper (setup.py) +pytest-xdist==3.6.1 + # via dapper (setup.py) +python-dateutil==2.9.0.post0 + # via + # arrow + # ghp-import + # jupyter-client + # matplotlib +python-json-logger==2.0.7 + # via jupyter-events +pyyaml==6.0.2 + # via + # dapper (setup.py) + # jupyter-events + # jupytext + # mkdocs + # mkdocs-get-deps + # pre-commit + # pybtex + # pymdown-extensions + # pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs +pyzmq==26.2.0 + # via + # ipykernel + # jupyter-client + # jupyter-console + # jupyter-server +readme-renderer==44.0 + # via twine +referencing==0.35.1 + # via + # jsonschema + # jsonschema-specifications + # jupyter-events +regex==2024.9.11 + # via mkdocs-material +requests==2.32.3 + # via + # jupyterlab-server + # mkdocs-material + # requests-toolbelt + # twine +requests-toolbelt==1.0.0 + # via twine +rfc3339-validator==0.1.4 + # via + # jsonschema + # jupyter-events +rfc3986==2.0.0 + # via twine +rfc3986-validator==0.1.1 + # via + # jsonschema + # jupyter-events +rich==13.9.3 + # via + # pytest-clarity + # twine +rpds-py==0.20.0 + # via + # jsonschema + # referencing +ruff==0.7.1 + # via dapper (setup.py) +scipy==1.14.1 + # via + # dapper (setup.py) + # mpl-tools + # patlib +send2trash==1.8.3 + # via jupyter-server +setuptools==75.3.0 + # via jupyterlab +six==1.16.0 + # via + # asttokens + # pybtex + # python-dateutil + # rfc3339-validator +sniffio==1.3.1 + # via + # anyio + # httpx +soupsieve==2.6 + # via beautifulsoup4 +stack-data==0.6.3 + # via ipython +struct-tools==0.2.5 + # via dapper (setup.py) +tabulate==0.8.10 + # via dapper (setup.py) +termcolor==2.5.0 + # via pytest-sugar +terminado==0.18.1 + # via + # jupyter-server + # jupyter-server-terminals +threadpoolctl==3.5.0 + # via dapper (setup.py) +tinycss2==1.4.0 + # via nbconvert +tornado==6.4.1 + # via + # dapper (setup.py) + # ipykernel + # jupyter-client + # jupyter-server + # jupyterlab + # notebook + # terminado +tox==4.23.2 + # via dapper (setup.py) +tqdm==4.66.6 + # via dapper (setup.py) +traitlets==5.14.3 + # via + # comm + # ipykernel + # ipython + # ipywidgets + # jupyter-client + # jupyter-console + # jupyter-core + # jupyter-events + # jupyter-server + # jupyterlab + # matplotlib-inline + # nbclient + # nbconvert + # nbformat +twine==5.1.1 + # via dapper (setup.py) +types-python-dateutil==2.9.0.20241003 + # via arrow +uri-template==1.3.0 + # via jsonschema +urllib3==2.2.3 + # via + # requests + # twine +virtualenv==20.27.1 + # via + # pre-commit + # tox +watchdog==5.0.3 + # via mkdocs +wcwidth==0.2.13 + # via prompt-toolkit +webcolors==24.8.0 + # via jsonschema +webencodings==0.5.1 + # via + # bleach + # tinycss2 +websocket-client==1.8.0 + # via jupyter-server +widgetsnbextension==4.0.13 + # via ipywidgets +zipp==3.20.2 + # via importlib-metadata