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.
Clone the documentation repository to your local machine.
git clone https://github.com/clearlinux/clear-linux-documentationMake sure you have Python 3 installed to start.
The Sphinx documentation provides instructions for installing Sphinx on various platforms.
Use pip3 to install additional Python dependencies listed in the requirements.txt file found in the repository:
pip3 install -r requirements.txtWe build our documentation using Sphinx. In the source directory of your
local clear-linux-documentation repository, preview changes to the
documentation by building the docs in the default language (English) by
running make html:
make htmlsphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.8.0
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 found in source/_build/html in a web browser
to view the rendered documentation.
If you want to build the documentation exactly as seen on the website, use
make py followed by make htmlall. This builds some
external dependencies and all supported languages.
When testing changes in the documentation, make sure to remove the previous
build before building again by running make clean:
make cleanThis will completely remove the previous build output.
This bash script (Linux only) includes both make clean and
make html. It also starts a simple Python web server that
displays a preview of the site at http://localhost:8000 on your local machine.
./checkwork.shTo stop the web server simply use ctrl-c.