Add docs on how to build docs

I put some docs in your docs on building docs, so now I can build docs
about my docs from my docs.
This commit is contained in:
Tim Heap 2016-03-03 06:43:55 +02:00 committed by Matt Westcott
parent 83ab0746bc
commit 84432fbfd6

View file

@ -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 <http://localhost:8080/> 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