Documentation/writing_documentation.md: Explain how to use docker

Using docker to build to documentation eases the process of building
the documentation. Given that some versions of sphinx are
incompatible, the option to use docker is presented first.

Change-Id: I6c18f81a829364ada1859c04ba2dc4f886934bcc
Signed-off-by: Arthur Heymans <arthur@aheymans.xyz>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/36105
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
This commit is contained in:
Arthur Heymans 2019-10-17 22:16:12 +02:00 committed by Martin Roth
parent 523ca8d9b0
commit 11b910281e
1 changed files with 23 additions and 1 deletions

View File

@ -14,7 +14,29 @@ coreboot uses [Sphinx] documentation tool. We prefer the markdown format
over reStructuredText so only embedded ReST is supported. Checkout the over reStructuredText so only embedded ReST is supported. Checkout the
[Markdown Guide] for more information. [Markdown Guide] for more information.
### Install Sphinx ### option 1: Use the docker image
The easiest way to build the documentation is using a docker image.
To build the image run the following in the base directory:
make -C util/docker/ doc.coreboot.org
Before building the documentation make sure the output directory is given
the correct permissions before running docker.
mkdir -p Documentation/_build
To build the documentation:
make -C util/docker docker-build-docs
To have the documentation build and served over a web server live run:
make -C util/docker docker-livehtml-docs
On the host machine, open a browser to the address <http://0.0.0.0:8000>.
### option 2: Install Sphinx
Please follow this official [guide] to install sphinx. Please follow this official [guide] to install sphinx.
You will also need python-recommonmark for sphinx to be able to handle You will also need python-recommonmark for sphinx to be able to handle