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-documentation
Make 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.txt
We 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 html
sphinx-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.
This build will generate several warnings as there are two other optional make commands required to build the full documentation.
make py
to generate the bundle reference material.make man
to generate man page reference material.
To build the documentation exactly as seen on the website, use
make man
, make py
, and make htmlall
. This builds both
external dependencies and all supported languages.
To develop documentation in a virtualenv
, use the venv
target.
The Clear Linux OS documentation make target venv
provides a
simple development environment that ensures that you have the
latest packages and that you manage Python versions separately. Use of the
virtualenv
requires Python 3.6 or higher. For Windows examples below, use Powershell as an Administrator.
The virtual environment uses the same version of Python that was used to create the virtual environment.
Verify pip
is installed. A file path to pip should appear.
On Clear Linux OS and macOS*:
which pip
On Windows* 10 OS:
pip --version
If pip
is not installed, install it.
On Clear Linux OS and macOS:
python3 -m pip install --user --upgrade pip
On Windows 10 OS:
py -m pip install --upgrade pip
Note
This assumes Python was already added to your Windows path.
Install virtualenv
.
On Clear Linux OS and macOS*:
python3 -m pip install --user virtualenv
On Windows 10 OS:
py -m pip install --user virtualenv
Create the virtualenv
and install the required packages:
make venv
Activate the venv
.
source venv/bin/activate
Follow Run the build section to start developing documentation.
Remove the venv
when finished developing.
deactivate
When testing changes in the documentation, make sure to remove the previous
build before building again by running make clean
:
make clean
This will completely remove the previous build output, including artifacts from the make venv target when done outside an active venv.
Before running make man
, please run make clean-man
to clear out any
previous attempts.
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.sh
To stop the web server simply use ctrl-c
.