From 61baab70169672bb50b2eb12eb54ec44765ce9fa Mon Sep 17 00:00:00 2001 From: Leona Date: Mon, 16 Nov 2015 12:02:55 -0800 Subject: [PATCH 1/5] 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/ From 4be88534a63f29c4affa67f743a459d8fa47019a Mon Sep 17 00:00:00 2001 From: Leona Date: Wed, 18 Nov 2015 07:29:54 -0800 Subject: [PATCH 2/5] update README --- README.rst | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 192b0fd3..db49af06 100644 --- a/README.rst +++ b/README.rst @@ -2,10 +2,10 @@ 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. +makes it easy to build parsable, command-line readable, indexed, and search-friendly +documentation and APIs with `Sphinx`_. -Building with `Sphinx`_, however, requires a few prerequisites: +Building the docs with Sphinx, however, requires a few prerequisites: * `GNU make`_ * `Python`_ @@ -41,7 +41,7 @@ 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 + 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. @@ -49,7 +49,7 @@ Before running Sphinx, we need to correct some of the problems in the Gitlab rep 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. +box, and they don't quite work on Linux. .. code-block:: console @@ -61,21 +61,22 @@ box, and they don't quite work on Linux. These should be removed from ``master`` $ 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. + 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 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. +* 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. +* Run the builder only once. 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. +within an older clone of the :file:`project-docs/` directory. Blank answers indicate default. .. code-block:: console @@ -160,10 +161,10 @@ within the :file:`project-docs/` directory. Blank answers indicate default used 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` . +Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the :file:`source/` +directory before running :command:`make` ``html``. .. code-block:: console @@ -182,8 +183,8 @@ Open one of these pages in a web browser to view the rendered documentation. If 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`_. +For extra help and tips contributing docs in the .rst format needed for Clearlinux.org, see: +`Theming Sphinx`_. .. _GNU make: https://www.gnu.org/software/make/ .. _Python: https://www.python.org/ From 42af65be62048d7b356b0ea76e9a064c0ff27ad9 Mon Sep 17 00:00:00 2001 From: Leona Date: Wed, 18 Nov 2015 07:32:52 -0800 Subject: [PATCH 3/5] update README with link to Sphinx Docs project --- README.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/README.rst b/README.rst index db49af06..a4fb2c33 100644 --- a/README.rst +++ b/README.rst @@ -186,6 +186,7 @@ generate the new HTML, and your local Table of Contents should index and update For extra help and tips contributing docs in the .rst format needed for Clearlinux.org, see: `Theming Sphinx`_. +.. _Sphinx: http://sphinx-doc.org .. _GNU make: https://www.gnu.org/software/make/ .. _Python: https://www.python.org/ .. _PIP: https://pypi.python.org/pypi/pip/ From f57f093f62cc2cb0e73b1e5fab8736d540b0bddb Mon Sep 17 00:00:00 2001 From: Leona Date: Wed, 18 Nov 2015 07:37:39 -0800 Subject: [PATCH 4/5] update README with jump-to section link fixed --- README.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index a4fb2c33..4f4d2a8a 100644 --- a/README.rst +++ b/README.rst @@ -160,6 +160,8 @@ within an older clone of the :file:`project-docs/` directory. Blank answers ind make builder where "builder" is one of the supported builders, e.g. html, latex or linkcheck. +.. _run_make: + Run ``make`` ------------ @@ -169,6 +171,7 @@ directory before running :command:`make` ``html``. .. code-block:: console $ make html + > sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v1.3.1 making output directory... @@ -183,10 +186,10 @@ Open one of these pages in a web browser to view the rendered documentation. If 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 contributing docs in the .rst format needed for Clearlinux.org, 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 +.. _Sphinx: http://sphinx-doc.org/ .. _GNU make: https://www.gnu.org/software/make/ .. _Python: https://www.python.org/ .. _PIP: https://pypi.python.org/pypi/pip/ From e0f2e1d55ffd914950d274c833971e7ed7293ea4 Mon Sep 17 00:00:00 2001 From: Leona Date: Wed, 18 Nov 2015 07:41:12 -0800 Subject: [PATCH 5/5] one more try to fix ref linkage in README --- README.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index 4f4d2a8a..e330b9c8 100644 --- a/README.rst +++ b/README.rst @@ -162,11 +162,11 @@ within an older clone of the :file:`project-docs/` directory. Blank answers ind .. _run_make: -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``. +directory before running :command:`make` ``html``, or the doc format of your choice. .. code-block:: console