mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-07-27 15:05:52 +00:00
Bun K Tan
0f12f4cc1f
On 2017-11-30: -------------- 1) Created the download-image.rst file in the Guides/Maintaince. This is a hidden file and not visible under the Maintenance tree. This talks about types of Clear Linux images, how to verify checksum, and how to uncompress for Linux, macOS, and Windows. This is the base for other docs such as the bare-metal, live, bootable USBs (Linux, macOS, Windows), VMware docs... 2) Reworked the bootable-usb-linux.rst to re-use content from download-image.rst. 3) Reworked the bootable-usb-mac.rst to re-use content from download-image.rst. 4) Reworked the bootable-usb-windows.rst to re-use content from download-image.rst. 5) Reworked the live-image.rst to re-use content from bootable-usb-linux.rst and download-image.rst. 6) Reworked the bare-metal doc to re-use content from bootable-usb-linux.rst and download-image.rst. On 2017-12-01: -------------- 1) Updated the types of images list and created a table. 2) Remove references to the old "releases" repo. Users should only use the "image" folder - per engineering. On 2017-12-05: -------------- 1) Recaptured the 7zip screenshot and made it look better. 2) Added "download-image.rst" to the Guides/Maintenance/maintenance.rst" tree to make it visible. 3) Moved the "Download the latest Clear Linux image" out of the "download-image.rst" and put it into the "bootable-usb-linux.rst" and tagged it so it could be used by "bootable-usb-mac.rst" and "bootable-usb-windows.rst". On 2017-12-07: -------------- 1) Changed the "Types of images" list Guides/Maintenance/download-image.rst to a table format. On 2017-12-13: -------------- 1) Changed all instances of <> to [] to indicate substitution. 2) Added |CAUTION-BACKUP-USB| in substitution.rst. This is used in create-usb-linux.rst, create-usb-mac.rst, create-usb-windows.rst. 3) Deleted download-image.rst and created 3 new docs, one for each OS: download-verify-uncompress-linux.rst, download-verify-uncompress-mac.rst, download-verify-uncompress-windows.rst. 4) General fixes based on feedback. 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