diff --git a/README.rst b/README.rst index fb4507ad..114e23b9 100644 --- a/README.rst +++ b/README.rst @@ -1,12 +1,170 @@ -Summary -======= +Documentation Build Instructions +================================ -``project-docs`` is the project that hosts the documentation for the **Clear -Linux\* project for Intel® Architecture.** This source code was written in -reStructuredText format (``*.rst``) for its simplicity and then -converted/published in HTML. +ClearLinux Docs are written in :abbr:`ReStructuredText (ReST)` which makes for +easily-parsable, command-line readable, indexed and search-friendly documentation +and APIs. -Getting Started ---------------- +Building with `Sphinx`_, however, requires a few prerequisites: -These are the steps to generate html files for output validation. +* `GNU make`_ +* `Python`_ +* `PIP`_ + +The instructions for installing these varies according to OS. You can On a basic +out-of-the-box Ubuntu-like install, you might need something like: + +.. + + $ sudo apt-get install python-pip + $ sudo pip install -U sphinx sphinx-autobuild + +.. codeblock:: python + + $ python -c 'print __import__("sphinx").__version__' + 1.3.1 + +Dependencies fulfilled, let's now clone that gitlab repo: + +.. codeblock:: git + + $ git clone git@clrgitlab.intel.com:clr-documentation/project-docs.git + Cloning into 'project-docs'... + remote: Counting objects: 631, done. + remote: Compressing objects: 100% (583/583), done. + remote: Total 631 (delta 349), reused 108 (delta 35) + Receiving objects: 100% (631/631), 2.10 MiB | 0 bytes/s, done. + Resolving deltas: 100% (349/349), done. + Checking connectivity... done. + +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 the existing index file generated. These are remnants +of a build on a Windows box, and they don't quite work on Linux. These should be removed +from ``master`` eventually. + +.. codeblock:: shell-session + + $ cd project-docs/ + $ ls + make.bat Makefile source/ + $ rm -rf Makefile make.bat + $ 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 +run a native instance of :command:`sphinx-quickstart`. The program will run you through +a series of questons. 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. + +What follows here is a log from a successful :command:`sphinx-quickstart` build started from +within the :file:`project-docs/` directory. + +.. codeblock:: shell-session + + $ sphinx-quickstart + Welcome to the Sphinx 1.3.1 quickstart utility. + + Please enter values for the following settings (just press Enter to + accept a default value, if one is given in brackets). + + Enter the root path for documentation. + > Root path for the documentation [.]: source/ + + You have two options for placing the build directory for Sphinx output. + Either, you use a directory "_build" within the root path, or you separate + "source" and "build" directories within the root path. + > Separate source and build directories (y/n) [n]: n + + 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 [_]: + + The project name will occur in several places in the built documentation. + > Project name: ClearLinux Docs + > Author name(s): Intel OTC + + Sphinx has the notion of a "version" and a "release" for the + software. Each version can have multiple releases. For example, for + Python the version is something like 2.5 or 3.0, while the release is + something like 2.5.1 or 3.0a1. If you don't need this dual structure, + just set both to the same value. + > Project version: 1.0.0 + > Project release [1.0.0]: 1.0.0 + + If the documents are to be written in a language other than English, + you can select a language here by its language code. Sphinx will then + translate text that it generates into that language. + + For a list of supported codes, see + http://sphinx-doc.org/config.html#confval-language. + > Project language [en]: en + + The file name suffix for source files. Commonly, this is either ".txt" + or ".rst". Only files with this suffix are considered documents. + > Source file suffix [.rst]: .rst + + One document is special in that it is considered the top node of the + "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]: + + Sphinx can also add configuration for epub output: + > Do you want to use the epub builder (y/n) [n]: n + + Please indicate if you want to use one of the following Sphinx extensions: + > autodoc: automatically insert docstrings from modules (y/n) [n]: n + > doctest: automatically test code snippets in doctest blocks (y/n) [n]: n + > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: n + > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: n + > coverage: checks for documentation coverage (y/n) [n]: n + > pngmath: include math, rendered as PNG images (y/n) [n]: n + > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y + > ifconfig: conditional inclusion of content based on config values (y/n) [n]: y + > viewcode: include links to the source code of documented Python objects (y/n) [n]: y + + A Makefile and a Windows command file can be generated for you so that you + only have to run e.g. `make html' instead of invoking sphinx-build + directly. + > Create Makefile? (y/n) [y]: y + > Create Windows command file? (y/n) [n]: n + + Creating file source/conf.py. + Creating file source/index.rst. + Creating file source/Makefile. + + 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: + make builder + where "builder" is one of the supported builders, e.g. html, latex or linkcheck. + +Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the :file:`source/` +directory before running :command:`make` . + +.. codeblock:: make + + $ make html + sphinx-build -b html -d _build/doctrees . _build/html + Running Sphinx v1.3.1 + making output directory... + . + . + . + build succeeded, 9 warnings. + + Build finished. The HTML pages are in _build/html. + +Open a page in a web browser to view the rendered documentation. + +.. _GNU make: https://www.gnu.org/software/make/ +.. _Python: https://www.python.org/ +.. _PIP: https://pypi.python.org/pypi/pip/ \ No newline at end of file