From 74a725576f2338bf325821d9f9552161f1ec5c35 Mon Sep 17 00:00:00 2001 From: lochhh Date: Wed, 23 Oct 2024 18:04:02 +0100 Subject: [PATCH 1/8] Add `clean` action to Windows `make` file --- docs/make.bat | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/make.bat b/docs/make.bat index 79a8b01a..cae7e781 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -25,8 +25,16 @@ if errorlevel 9009 ( if "%1" == "" goto help -echo "Generating API index..." -python make_api_index.py +if "%1" == "clean" ( + @echo Removing auto-generated files under 'docs' and 'src'... + rmdir /S /Q %BUILDDIR% + del /Q %SOURCEDIR%\api_index.rst + rmdir /S /Q %SOURCEDIR%\api\ + rmdir /S /Q %SOURCEDIR%\examples\ +) else ( + @echo Generating API index... + python make_api_index.py +) %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end From a1ce7f38c50dd5a83b3e059befb12ac213939de7 Mon Sep 17 00:00:00 2001 From: lochhh Date: Wed, 23 Oct 2024 18:33:37 +0100 Subject: [PATCH 2/8] Use `fail-on-warning` mode in Windows `make` file --- docs/make.bat | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/make.bat b/docs/make.bat index cae7e781..c74405c2 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -9,6 +9,7 @@ if "%SPHINXBUILD%" == "" ( ) set SOURCEDIR=source set BUILDDIR=build +set SPHINXOPTS=-W %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( From 3a8854b30398fbacfd033288675147a55426fb0d Mon Sep 17 00:00:00 2001 From: lochhh Date: Wed, 23 Oct 2024 18:35:28 +0100 Subject: [PATCH 3/8] Drop unused `--keep-going` flag in Makefile --- docs/Makefile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 529f6650..da95f613 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,8 +4,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. # -W: if there are warnings, treat them as errors and exit with status 1. -# --keep-going: run sphinx-build to completion and exit with status 1 if errors. -SPHINXOPTS ?= -W --keep-going +SPHINXOPTS ?= -W SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build From a549aede27c0cf78cdf4b7239e036e92183b623a Mon Sep 17 00:00:00 2001 From: lochhh Date: Thu, 24 Oct 2024 11:50:09 +0100 Subject: [PATCH 4/8] Refactor auto-generate api docs --- docs/make_api_index.py | 37 +++++++++-------------- docs/source/_templates/api_index_head.rst | 3 ++ 2 files changed, 18 insertions(+), 22 deletions(-) diff --git a/docs/make_api_index.py b/docs/make_api_index.py index 37223112..c850022e 100644 --- a/docs/make_api_index.py +++ b/docs/make_api_index.py @@ -1,43 +1,36 @@ """Generate the API index page for all ``movement`` modules.""" import os +from pathlib import Path # Modules to exclude from the API index exclude_modules = ["cli_entrypoint"] # Set the current working directory to the directory of this script -script_dir = os.path.dirname(os.path.abspath(__file__)) +script_dir = Path(__file__).resolve().parent os.chdir(script_dir) def make_api_index(): """Create a doctree of all ``movement`` modules.""" doctree = "\n" - - for root, _, files in os.walk("../movement"): - # Remove leading "../" - root = root[3:] - for file in sorted(files): - if file.endswith(".py") and not file.startswith("_"): - # Convert file path to module name - module_name = os.path.join(root, file) - module_name = module_name[:-3].replace(os.sep, ".") - # Check if the module should be excluded - if not any( - file.startswith(exclude_module) - for exclude_module in exclude_modules - ): - doctree += f" {module_name}\n" - + api_path = Path("../movement") + for path in sorted(api_path.rglob("*.py")): + if path.name.startswith("_"): + continue + # Convert file path to module name + rel_path = path.relative_to(api_path.parent) + module_name = str(rel_path.with_suffix("")).replace(os.sep, ".") + if rel_path.stem not in exclude_modules: + doctree += f" {module_name}\n" # Get the header - with open("./source/_templates/api_index_head.rst") as f: - api_head = f.read() + api_head_path = Path("source") / "_templates" / "api_index_head.rst" + api_head = api_head_path.read_text() # Write api_index.rst with header + doctree - with open("./source/api_index.rst", "w") as f: - f.write("..\n This file is auto-generated.\n\n") + output_path = Path("source") / "api_index.rst" + with output_path.open("w") as f: f.write(api_head) f.write(doctree) - print(os.path.abspath("./source/api_index.rst")) if __name__ == "__main__": diff --git a/docs/source/_templates/api_index_head.rst b/docs/source/_templates/api_index_head.rst index f1df7eb6..0c1e6b7e 100644 --- a/docs/source/_templates/api_index_head.rst +++ b/docs/source/_templates/api_index_head.rst @@ -1,3 +1,6 @@ +.. + This file is auto-generated. + .. _target-api: API Reference From fd4f3269c9202464a8f662f9653ff6af9591f977 Mon Sep 17 00:00:00 2001 From: lochhh Date: Thu, 24 Oct 2024 16:37:12 +0100 Subject: [PATCH 5/8] Update contributing docs --- CONTRIBUTING.md | 43 ++++++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f350fdb..8696629a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -292,51 +292,60 @@ All subsequent commands should be run from this directory. To build the documentation, run: ::::{tab-set} -:::{tab-item} Unix platforms with `make` +:::{tab-item} `make` mode ```sh make html ``` The local build can be viewed by opening `docs/build/html/index.html` in a browser. ::: -:::{tab-item} All platforms +:::{tab-item} Default mode ```sh -python make_api_index.py && sphinx-build source build -W --keep-going +python make_api_index.py && sphinx-build source build -W ``` The local build can be viewed by opening `docs/build/index.html` in a browser. ::: :::: -To re-build the documentation after making changes, run the command below. It will remove all generated files in `docs/`, -including the auto-generated API index `source/api_index.rst`, and those in `build/`, `source/api/`, and `source/examples/`, and then re-build the documentation. +To re-build the documentation after making changes, we recommend removing existing build files first. +The following command will remove all generated files in `docs/`, +including the auto-generated API index `source/api_index.rst`, and those in `build/`, `source/api/`, and `source/examples/`. Once the files are removed, you can re-build the documentation as described above. -::::{tab-set} -:::{tab-item} Unix platforms with `make` +::::::{tab-set} +:::::{tab-item} `make` mode ```sh -make clean html +make clean ``` -::: +::::: -:::{tab-item} All platforms +:::::{tab-item} Default mode +::::{tab-set} +:::{tab-item} Unix ```sh rm -f source/api_index.rst && rm -rf build && rm -rf source/api && rm -rf source/examples -python make_api_index.py && sphinx-build source build -W --keep-going +``` +::: +:::{tab-item} Windows +```sh +rm -fo source/api_index.rst && rm -r -fo build, source/api, source/examples ``` ::: :::: +::::: +:::::: To check that external links are correctly resolved, run: ::::{tab-set} -:::{tab-item} Unix platforms with `make` +:::{tab-item} `make` mode ```sh make linkcheck ``` ::: -:::{tab-item} All platforms +:::{tab-item} Default mode ```sh -sphinx-build source build -b linkcheck -W --keep-going +sphinx-build source build -b linkcheck -W ``` ::: :::: @@ -399,9 +408,9 @@ To add a new file, you will need to: 6. Determine the sha256 checksum hash of each new file. You can do this in a terminal by running: ::::{tab-set} :::{tab-item} Ubuntu - ```bash - sha256sum - ``` + ```bash + sha256sum + ``` ::: :::{tab-item} MacOS From 58bd5bc6bfeef2919ce62e763696a3f6a2f6ede6 Mon Sep 17 00:00:00 2001 From: lochhh Date: Thu, 24 Oct 2024 16:38:14 +0100 Subject: [PATCH 6/8] Remove Sphinx version constraint --- docs/requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 63615d66..0a950f2e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,7 +4,7 @@ myst-parser nbsphinx pydata-sphinx-theme setuptools-scm -sphinx>=7.0 +sphinx sphinx-autodoc-typehints sphinx-design sphinx-gallery From 8a9e320c39e2188d925a218b9dc13fc155d14820 Mon Sep 17 00:00:00 2001 From: lochhh Date: Thu, 24 Oct 2024 19:28:57 +0100 Subject: [PATCH 7/8] Document make-mode only --- CONTRIBUTING.md | 49 +++++++++---------------------------------------- 1 file changed, 9 insertions(+), 40 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8696629a..e11b03fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -291,64 +291,24 @@ All subsequent commands should be run from this directory. To build the documentation, run: -::::{tab-set} -:::{tab-item} `make` mode ```sh make html ``` The local build can be viewed by opening `docs/build/html/index.html` in a browser. -::: - -:::{tab-item} Default mode -```sh -python make_api_index.py && sphinx-build source build -W -``` -The local build can be viewed by opening `docs/build/index.html` in a browser. -::: -:::: To re-build the documentation after making changes, we recommend removing existing build files first. The following command will remove all generated files in `docs/`, including the auto-generated API index `source/api_index.rst`, and those in `build/`, `source/api/`, and `source/examples/`. Once the files are removed, you can re-build the documentation as described above. -::::::{tab-set} -:::::{tab-item} `make` mode ```sh make clean ``` -::::: - -:::::{tab-item} Default mode -::::{tab-set} -:::{tab-item} Unix -```sh -rm -f source/api_index.rst && rm -rf build && rm -rf source/api && rm -rf source/examples -``` -::: -:::{tab-item} Windows -```sh -rm -fo source/api_index.rst && rm -r -fo build, source/api, source/examples -``` -::: -:::: -::::: -:::::: To check that external links are correctly resolved, run: -::::{tab-set} -:::{tab-item} `make` mode ```sh make linkcheck ``` -::: - -:::{tab-item} Default mode -```sh -sphinx-build source build -b linkcheck -W -``` -::: -:::: If the linkcheck step incorrectly marks links with valid anchors as broken, you can skip checking the anchors in specific links by adding the URLs to `linkcheck_anchors_ignore_for_url` in `docs/source/conf.py`, e.g.: @@ -361,6 +321,15 @@ linkcheck_anchors_ignore_for_url = [ ] ``` +:::{tip} +The `make` commands can be combined to run multiple tasks sequentially. +For example, to clean the build directory, build the documentation, and check the links, run: +```sh +make clean html linkcheck # Unix-like systems +make clean && make html && make linkcheck # Windows systems +``` +::: + ## Sample data We maintain some sample datasets to be used for testing, examples and tutorials on an From bb6437c49cf6836c4b617e012eb4604c88e385a7 Mon Sep 17 00:00:00 2001 From: lochhh Date: Thu, 24 Oct 2024 19:51:44 +0100 Subject: [PATCH 8/8] Allow target chaining in Windows make --- CONTRIBUTING.md | 9 ++++----- docs/make.bat | 6 +++++- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e11b03fa..63dc93bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -298,10 +298,10 @@ The local build can be viewed by opening `docs/build/html/index.html` in a brows To re-build the documentation after making changes, we recommend removing existing build files first. The following command will remove all generated files in `docs/`, -including the auto-generated API index `source/api_index.rst`, and those in `build/`, `source/api/`, and `source/examples/`. Once the files are removed, you can re-build the documentation as described above. +including the auto-generated API index `source/api_index.rst`, and those in `build/`, `source/api/`, and `source/examples/`. It will then re-build the documentation: ```sh -make clean +make clean html ``` To check that external links are correctly resolved, run: @@ -323,10 +323,9 @@ linkcheck_anchors_ignore_for_url = [ :::{tip} The `make` commands can be combined to run multiple tasks sequentially. -For example, to clean the build directory, build the documentation, and check the links, run: +For example, to re-build the documentation and check the links, run: ```sh -make clean html linkcheck # Unix-like systems -make clean && make html && make linkcheck # Windows systems +make clean html linkcheck ``` ::: diff --git a/docs/make.bat b/docs/make.bat index c74405c2..b1e18dd6 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -26,6 +26,7 @@ if errorlevel 9009 ( if "%1" == "" goto help +:process_targets if "%1" == "clean" ( @echo Removing auto-generated files under 'docs' and 'src'... rmdir /S /Q %BUILDDIR% @@ -35,9 +36,12 @@ if "%1" == "clean" ( ) else ( @echo Generating API index... python make_api_index.py + %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% ) -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +shift +if not "%1" == "" goto process_targets + goto end :help