diff --git a/Documentation/docs/README.md b/Documentation/docs/README.md index ba4539793bc..eae2c518e4f 100644 --- a/Documentation/docs/README.md +++ b/Documentation/docs/README.md @@ -1,14 +1,30 @@ -# Sphinx Documentation +## How to contribute documentation improvements -This is the source of the [ITK docs](docs.itk.org) website. +Thank you for improving our documentation! Every addition made is read +thousands of times and has a tremendous impact. -## Build environment +These are the sources for the [ITK docs](docs.itk.org) +[sphinx](https://www.sphinx-doc.org/) website. + +The contribution process generally follows our [contributing +guidelines](../../CONTRIBUTING.md). + +To preview documentation changes, three options are available. + +### Option 0: Edit on GitHub, use the pull request preview. + +If files are edited with GitHub's web user interface, the pull request will +build a preview of changes with a pull request check called `docs/readthedocs.org:itk`. +Click on the *Details* link to view the documentation build preview. + +### Option 1: Build and serve locally To compile the document locally create a python virtual environment and install the required packages. For example in Linux / macOS: -``` +```sh +cd ITK/Documentation/docs python -m venv env source env/bin/activate pip install -r requirements.txt @@ -16,3 +32,20 @@ pip install -r requirements.txt Use `make html` in this directory to build the documentation. Open `_build/html/index.html` in your browser to inspect the result. + +### Option 2: Autobuild and serve locally + +To automatically rebuild the website with any input markdown changes and serve +the result, use [sphinx-autobuild] + +```sh +pip install sphinx-autobuild +``` + +``` +cd ITK/Documentation/docs +sphinx-autobuild -a . _build/html +``` + +This will start a server at [http://127.0.0.1:8000](http://127.0.0.1:8000) +and rebuild whenever the documentation changes.