mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-07-24 13:35:55 +00:00
Bun K Tan
cb1efed189
2) Added minimum memory size (with screenshot) info for Method 2. >>> 2017-11-17 Converted figure substitutions to inlines. >>> 2017-11-21 1) Added brief intro of what ESXi is. 2) Updated the "Download the latest Clear Linux image" section to tell which image to download based on the "Method" type. 3) Added a "Note" to the beginning of "Verify" and "Uncompress" sections to say that the command-line examples reference an "installer ISO" and to substitute as needed. 4) Added reference to the "Workstation" version of VMware in the intro. 5) tagged the "Download", "Verify", and "Uncompressed" sections so they can be re-used in the VMware Workstation doc. >>> 2017-12-05 1) Moved the "Download", "Verify", and "Uncompress" sections under "Method 1". 2) Re-using the "Types of images", "Verify", "Uncompress" modules from Guides/Maintaince/download-image.rst. >>> 2017-12-07 1) Made changes based on feedback. 2) Reused content from Guides/Maintenance/download-image.rst. 3) Created labels for each section and ref'ed them at the beginning of each "Method". 4) Updated Figure 26. Signed-off-by: Bun K Tan <bun.k.tan@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