mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-21 11:06:14 +00:00
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:
committed by
michael vincerra
parent
6ac6b4812b
commit
5a041baa1c
+55
-26
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user