diff --git a/README.rst b/README.rst index e330b9c8..995dd54c 100644 --- a/README.rst +++ b/README.rst @@ -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/