Skip to content

Commit

Permalink
Document make-mode only
Browse files Browse the repository at this point in the history
  • Loading branch information
lochhh committed Oct 24, 2024
1 parent 58bd5bc commit 8a9e320
Showing 1 changed file with 9 additions and 40 deletions.
49 changes: 9 additions & 40 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.:

Expand All @@ -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
Expand Down

0 comments on commit 8a9e320

Please sign in to comment.