Updated readme to reflect recent changes and latest doc BKMs. (#737)

* Updated readme to reflect recent changes and latest doc BKMs.

Signed-off-by: Kevin Putnam <kevin.putnam@intel.com>

* Fixes typo in subheader, Cleaning up.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
Kevin Putnam
2019-09-19 18:30:26 -07:00
committed by michael vincerra
parent 6ac6b4812b
commit 5a041baa1c
+55 -26
View File
@@ -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