mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-28 13:45:43 +00:00
Rodrigo Caballero
34a0b6050f
This restructure organizes the content into three sections, one per technology. The content was left as untouched as possible, however several directives needed to be standardized in order to implement the new structure. All filenames follow use dashes-as-spaces and are written using lower-case. Standard labels for files were implemented using the filename as the label, thus, content can be cross-referenced without having to open the file to see the label. Figures were moved to decentralized folders to enable modularity. The scope of the restructure as well as the dependencies between the changes required me to do it in a single commit. Lastly, some cleanup had to be done for the standardized structure to function properly. Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
84 lines
2.2 KiB
ReStructuredText
84 lines
2.2 KiB
ReStructuredText
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 git@clrgitlab.intel.com:clr-documentation/project-docs.git
|
|
|
|
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
|