diff --git a/README.rst b/README.rst index ab37040d..4a7db55c 100644 --- a/README.rst +++ b/README.rst @@ -10,38 +10,46 @@ documentation locally for development and testing. Please make yourself familiar with our `contribution guidelines`_ before submitting a contribution. -Requirements -************ - -Make sure you have Python and Sphinx installed. We use Python 3 and -Sphinx 1.7.5 - -The Sphinx documentation provides `instructions for installing Sphinx`_ on various -platforms. - Clone the documentation repository ********************************** -Once Sphinx is installed, clone the documentation repository to your -local machine. +Clone the documentation repository to your local machine. -.. code-block:: console +.. code-block:: bash - $ git clone https://github.com/clearlinux/clear-linux-documentation + git clone https://github.com/clearlinux/clear-linux-documentation + +Requirements +************ + +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: + +.. code-block:: bash + + pip3 install -r requirements.txt Run the build ************* We build our documentation using Sphinx. In the source directory of your -local clear-linux-documentation repository, build the documentation by running -**make html**: +local clear-linux-documentation repository, preview changes to the +documentation by building the docs in the default language (English) by +running ``make html``: + +.. code-block:: bash + + make html .. code-block:: console - $ make html - > sphinx-build -b html -d _build/doctrees . _build/html - Running Sphinx v1.7.5 + Running Sphinx v1.8.0 making output directory... . . @@ -52,21 +60,42 @@ local clear-linux-documentation repository, build the documentation by running Build finished. The HTML pages are in _build/html. -Open one of the HTML pages in a web browser to view the rendered -documentation. +Open one of the HTML pages found in ``source/_build/html`` in a web browser +to view the rendered documentation. + +If you want to build the documentation exactly as seen on the website, use +``make py`` followed by ``make htmlall``. This builds some +external dependenices and all supported languages. + +Additional help +*************** + +Cleaning up +=========== When testing changes in the documentation, make sure to remove the previous -build before building again by running **make clean**: +build before building again by running ``make clean``: -.. code-block:: console +.. code-block:: bash - $ make clean - > - rm -rf _build/* + make clean This will completely remove the previous build output. -.. _Clear Linux\* OS documentation: https://clearlinux.org/documentation +Convenience script +================== + +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. + +.. code-block:: bash + + ./checkwork.sh + +To stop the web server simply use ``ctrl-c``. + +.. _Clear Linux\* OS documentation: https://docs.01.org/clearlinux/ .. _Sphinx: http://sphinx-doc.org/ .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration