clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-09-04 04:41:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleanup README

Browse Source
This commit is contained in:
Leona
2015-11-23 08:02:15 -08:00
parent 3efb9d787e
commit 3891716c55
1 changed files with 47 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.rst
+47 -31
View File
@@ -5,6 +5,12 @@ ClearLinux Docs are written in :abbr:`ReStructuredText (ReST)` AKA ``.rst``, whi
makes it easy to build parsable, command-line readable, indexed, and search-friendly
documentation and APIs with `Sphinx`_.
.. _requirements:
Requirements
------------
Building the docs with Sphinx, however, requires a few prerequisites:
* `GNU make`_
@@ -40,16 +46,18 @@ Dependencies fulfilled, let's now clone that gitlab repo:
.. tip::
If the first time you've cloned the ``project-docs`` is following along with this tutorial,
you can skip this section; go straight ahead to the :ref:`Run make` section. However, if you
cloned an earlier version and had trouble generating HTML documentation locally, try the steps
documented here.
If the first time you've cloned ``project-docs`` is following along
with this tutorial, you may skip this section; go straight ahead to the
:ref:`Run make` section. However, if you cloned an earlier version and
had trouble generating HTML documentation locally, try the steps documented
here.
Before running Sphinx, we need to correct some of the problems in the Gitlab repo.
Running :command:`make` straightaway from the root of our clone won't work. We need to delete the
existing :file:`conf.py` file and also rename the existing index file so it can generate a new one
with the correct parameters. Some files in the Gitlab repo are remnant of a build on a Windows
box, and they don't quite work on Linux.
Before running Sphinx, we need to correct some of the problems in the Gitlab
repo. Running :command:`make` straightaway from the root of our clone won't
work. We need to delete the existing :file:`conf.py` file and also rename
the existing index file so it can generate a new one with the correct
parameters. Some files in the Gitlab repo are remnant of a build on a Windows
box, and they don't quite work on Linux.
.. code-block:: console
@@ -61,22 +69,26 @@ box, and they don't quite work on Linux.
$ mv source/index.rst source/oldindex.rst
In the cloned source directory, we have all the .rst files we need to build the docs. We
run a native instance of :command:`sphinx-quickstart`. The program will run you through
a series of questions. The main things to be conscious of here:
In the cloned source directory, we have all the .rst files we need to build
the docs. We run a native instance of :command:`sphinx-quickstart`. The
program will run you through a series of questions. The main things to be
conscious of here:
* Tell it to use the existing :file:`source/` directory as the Root path for
the documentation; this is where it looks to find what it needs to generate the HTML.
* It's better to tell it to **not** separate the source and build directories; if you
answer "y" here, Sphinx will generate *another* :file:`source/` directory, which
can be confusing.
* The running quickstart also creates as :file:`_static` directory where you should put
all images, screenshots, and other static content. The builder might complain about this
directory if it exists already, but it's easy to fix.
the documentation; this is where it looks to find what it needs to generate
the HTML.
* It's better to tell it to **not** separate the source and build directories;
if you answer "y" here, Sphinx will generate *another* :file:`source/` directory,
which can be confusing.
* Running quickstart also creates a :file:`_static` directory where you
should put all images, screenshots, and other content that is linked as static
content. The builder has been known to complain about this directory if it exists
already, but it's easy to fix.
* Run the builder only once.
What follows here is a log from a successful :command:`sphinx-quickstart` build started from
within an older clone of the :file:`project-docs/` directory. Blank answers indicate default.
What follows here is a log from a successful :command:`sphinx-quickstart` build
started from within an older clone of the :file:`project-docs/` directory. Blank
answers indicate default.
.. code-block:: console
@@ -155,18 +167,20 @@ within an older clone of the :file:`project-docs/` directory. Blank answers ind
Finished: An initial directory structure has been created.
You should now populate your master file source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
You should now populate your master file source/index.rst and create other
documentation source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
where "builder" is one of the supported builders, e.g. html, latex or
linkcheck.
.. _run_make:
Run make
--------
Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the :file:`source/`
directory before running :command:`make` ``html``, or the doc format of your choice.
Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the
:file:`source/` directory before running :command:`make` ``html``, or the doc
format of your choice.
.. code-block:: console
@@ -182,12 +196,14 @@ directory before running :command:`make` ``html``, or the doc format of your cho
Build finished. The HTML pages are in _build/html.
Open one of these pages in a web browser to view the rendered documentation. If needed, you can
copy the contents of the oldindex.rst into the generated index file, re-run :command:`make`, to
generate the new HTML, and your local Table of Contents should index and update accordingly.
Open one of these pages in a web browser to view the rendered documentation.
If needed, you can copy the contents of the oldindex.rst into the generated
index file, re-run :command:`make`, to generate the new HTML, and your local
Table of Contents should index and update accordingly.
For tips on how to contribute documentation formatted in the .rst style needed to integrate on the
Clearlinux.org website, please see `Theming Sphinx`_.
For tips on how to contribute documentation formatted in the .rst style
needed to integrate on the Clearlinux.org website, please see
`Theming Sphinx`_.
.. _Sphinx: http://sphinx-doc.org/
.. _GNU make: https://www.gnu.org/software/make/