mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-24 08:48:15 +00:00
Jair Gonzalez
30869c1fa3
The default data directory for Apache is /var/www/html in the latest version (tested on VERSION_ID=20490), instead of /usr/share/httpd/htdocs as specified in the web-server-install tutorial. This causes several inconsistencies in the "Change the Default Configuration and Data Directory" section. This commit updates the steps to configure a different data directory for demostrative purposes (/var/www/tutorial) as the proposed one (/var/www/html) is currently the default value. As the rest of the document and the WordPress server tutorial refers to /var/www/html, it's also necesary to add aditional steps to return the configuration back to the original values to leave it ready for the user to be able to follow the next steps in this and the WordPress tutorials. Signed-off-by: Jair Gonzalez <jair.de.jesus.gonzalez.plascencia@intel.com>
Documentation Build Instructions
################################
The `website documentation`_ for Clear Linux\* OS for Intel Architecture
should be written in :abbr:`ReStructuredText (ReST)` AKA ``.rst``, which
makes it easy to build parsable, command-line readable, indexed, and
search-friendly documentation and APIs with `Sphinx`_.
.. _requirements:
Requirements
============
To build documentation with Sphinx, ensure your system has these
prerequisites:
* `GNU make`_
* `Python`_
* `PIP`_
* `Sphinx`_
The instructions for installing these varies according to OS. On a basic out-
of-the-box Ubuntu-like OS (which usually has Python installed by default),
check your python version you might need something like:
.. code-block:: console
$ sudo apt-get install python-pip
$ sudo pip install -U sphinx sphinx-autobuild
.. code-block:: console
$ python -c 'print __import__("sphinx").__version__'
1.3.1
Cloning the documentation repository
====================================
We have confirmed Sphinx installed. The next step is to clone Gitlab
repository to our local machine.
.. code-block:: console
$ git clone https://github.com/clearlinux/clear-linux-documentation
Run make
========
Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the
:file:`source/` directory where your ``.rst`` files are, before
running :command:`make html`, or the doc format of your choice.
.. code-block:: console
$ make html
>
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.3.1
making output directory...
.
.
.
build succeeded, 0 warnings.
Build finished. The HTML pages are in _build/html.
Open one of the .html pages in a web browser to view the rendered
documentation.
For tips on how to contribute documentation formatted in the .rst style
needed to integrate beautifully on the clearlinux.org website, please see
`Theming Sphinx`_.
.. _website documentation: https://clearlinux.org/documentation
.. _Sphinx: http://sphinx-doc.org/
.. _GNU make: https://www.gnu.org/software/make/
.. _Python: https://www.python.org/
.. _PIP: https://pypi.python.org/pypi/pip/
.. _Theming Sphinx: https://github.com/otcshare/tcs-hub/blob/master/theming-sphinx.rst