From 61baab70169672bb50b2eb12eb54ec44765ce9fa Mon Sep 17 00:00:00 2001 From: Leona Date: Mon, 16 Nov 2015 12:02:55 -0800 Subject: [PATCH] updating README; merge into master means one section of the README is conditional to when you cloned repo --- README.rst | 66 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 26 deletions(-) diff --git a/README.rst b/README.rst index 1332ee30..192b0fd3 100644 --- a/README.rst +++ b/README.rst @@ -3,13 +3,13 @@ Documentation Build Instructions ClearLinux Docs are written in :abbr:`ReStructuredText (ReST)` AKA ``.rst``, which makes for easily-parsable, command-line readable, indexed and search-friendly -documentation and APIs. +documentation and APIs. -Building with `Sphinx`_, however, requires a few prerequisites: +Building with `Sphinx`_, however, requires a few prerequisites: -* `GNU make`_ -* `Python`_ -* `PIP`_ +* `GNU make`_ +* `Python`_ +* `PIP`_ The instructions for installing these varies according to OS. On a basic out-of-the-box Ubuntu-like OS (which usually has Python installed by default), @@ -20,12 +20,12 @@ you might need something like: $ sudo apt-get install python-pip $ sudo pip install -U sphinx sphinx-autobuild -.. code-block:: console - +.. code-block:: console + $ python -c 'print __import__("sphinx").__version__' 1.3.1 -Dependencies fulfilled, let's now clone that gitlab repo: +Dependencies fulfilled, let's now clone that gitlab repo: .. code-block:: console @@ -38,10 +38,17 @@ Dependencies fulfilled, let's now clone that gitlab repo: Resolving deltas: 100% (349/349), done. Checking connectivity... done. +.. 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. + Before running Sphinx, we need to correct some of the problems in the Gitlab repo. -Running :command:`make` straightaway from our clone won't work. We need to delete the -existing conf.py file and also rename the existing index file so it can generate a new one -with the correct parameters. These files in the Gitlab repo are remnant of a build on a Windows +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. These should be removed from ``master`` eventually. .. code-block:: console @@ -50,20 +57,24 @@ box, and they don't quite work on Linux. These should be removed from ``master`` $ ls make.bat Makefile source/ $ rm -rf Makefile make.bat - $ rm -rf source/conf.py + $ rm -rf source/conf.py $ 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 +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 what it looks in, in order to generate the HTML -* It's better to tell it to **not** separate the source and build directories; the Sphinx - will generate *another* :file:`source/` directory, which can be confusing. +* Tell it to use the existing :file:`source/` directory as the Root path for + the documentation; this is what it looks in, in order 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 new master now has a :file:`_static` directory where you should put all images, screenshots, + and other static content. The builder might complain about this, but it's easy to fix. You + need run the builder only once. -What follows here is a log from a successful :command:`sphinx-quickstart` build started from +What follows here is a log from a successful :command:`sphinx-quickstart` build started from within the :file:`project-docs/` directory. Blank answers indicate default used. .. code-block:: console @@ -85,7 +96,7 @@ within the :file:`project-docs/` directory. Blank answers indicate default used Inside the root directory, two more directories will be created; "_templates" for custom HTML templates and "_static" for custom stylesheets and other static files. You can enter another prefix (such as ".") to replace the underscore. - > Name prefix for templates and static dir [_]: + > Name prefix for templates and static dir [_]: The project name will occur in several places in the built documentation. > Project name: ClearLinux Docs @@ -115,7 +126,7 @@ within the :file:`project-docs/` directory. Blank answers indicate default used "contents tree", that is, it is the root of the hierarchical structure of the documents. Normally, this is "index", but if your "index" document is a custom template, you can also set this to another filename. - > Name of your master document (without suffix) [index]: + > Name of your master document (without suffix) [index]: Sphinx can also add configuration for epub output: > Do you want to use the epub builder (y/n) [n]: n @@ -148,8 +159,11 @@ within the :file:`project-docs/` directory. Blank answers indicate default used make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck. +Run ``make`` +~~~~~~~~~~~~~ + Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the :file:`source/` -directory before running :command:`make` . +directory before running :command:`make` . .. code-block:: console @@ -160,16 +174,16 @@ directory before running :command:`make` . . . . - build succeeded, 9 warnings. + build succeeded, 0 warnings. Build finished. The HTML pages are in _build/html. -Open one of these pages in a web browser to view the rendered documentation. 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 extra help and tips for contributing documentation which will render beautifully on websites, -despite being written in .rst see: `Theming_Sphinx`_. +despite being written in .rst see: `Theming Sphinx`_. .. _GNU make: https://www.gnu.org/software/make/ .. _Python: https://www.python.org/