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