Documentation build instructions

Clear Linux* OS documentation is written using reStructuredText and built using Sphinx. Follow the instructions in this README to build the documentation locally for development and testing.

Please make yourself familiar with our contribution guidelines before submitting a contribution.

Requirements

Make sure you have Python and Sphinx installed. We use Python 3 and Sphinx 1.7.5

The Sphinx documentation provides instructions for installing Sphinx on various platforms.

Clone the documentation repository

Once Sphinx is installed, clone the documentation repository to your local machine.

$ git clone https://github.com/clearlinux/clear-linux-documentation

Run the build

We build our documentation using Sphinx. In the source directory of your local clear-linux-documentation repository, build the documentation by running make html:

$ make html
>
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.7.5
making output directory...
.
.
.
build succeeded, 0 warnings.

The HTML pages are in _build/html.

Build finished. The HTML pages are in _build/html.

Open one of the HTML pages in a web browser to view the rendered documentation.

When testing changes in the documentation, make sure to remove the previous build before building again by running make clean:

$ make clean
>
rm -rf _build/*

This will completely remove the previous build output.