diff --git a/docs/contributing/developing.rst b/docs/contributing/developing.rst index 8e23a5f9c..f753fc176 100644 --- a/docs/contributing/developing.rst +++ b/docs/contributing/developing.rst @@ -110,3 +110,42 @@ This must be done after every change to the source files. To watch the source fi .. code-block:: sh npm start + +Compiling the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Wagtail documentation is built by Sphinx. To install Sphinx and compile the documentation, run: + +.. code-block:: sh + + cd /path/to/wagtail + # Install the documentation dependencies + pip install -e .[docs] + # Compile the docs + cd docs/ + make html + +The compiled documentation will now be in ``docs/_build/html``. +Open this directory in a web browser to see it. +Python comes with a module that makes it very easy to preview static files in a web browser. +To start this simple server, run the following commands: + +.. code-block:: sh + + $ cd docs/_build/html/ + # Python 2 + $ python2 -mSimpleHTTPServer 8080 + # Python 3 + $ python3 -mhttp.server 8080 + +Now you can open in your web browser to see the compiled documentation. + +Sphinx caches the built documentation to speed up subsequent compilations. +Unfortunately, this cache also hides any warnings thrown by unmodified documentation source files. +To clear the built HTML and start fresh, so you can see all warnings thrown when building the documentation, run: + +.. code-block:: sh + + $ cd docs/ + $ make clean + $ make html