nacl-docs-rst
=============

Directory structure
-------------------

This is a tree of .rst files that represent the source of the NaCl
documentation. Some of the files and directories here are special:

* conf.py: Sphinx configuration file
* images/: Images are stored here. Note that this isn't necessary - Sphinx
  doesn't mind about interspersing images in .rst directories.
* _sphinxext/: Code of the Sphinx extension we use to generate HTML from .rst
* _static/: Static files, like CSS, for the documentation. This should be seen
  as part of the infrastructure - the real CSS comes from the real doc
  publishing server.
* _build/: Build artifacts (not checked into source control).
* Makefile & README

How to build
------------

To build the docs you will needs sphinx installed (and sphinx-build in your
path).  On debian/ubuntu this command is part of the ``python-sphinx`` package.

There are many different output formats that can be generated using the targets
in the included Makefile.  The three most commonly used ones are ``devsite``,
``devsite-prod`` and ``devsite-staging``.

The ``devsite`` configuration is for generating docs for local viewing and is
also the default make target.  To build this config simply run::

  make

To rebuild all the pages always, add ``SPHINXOPTS=-a``, e.g.::

  make SPHINXOPTS=-a

To emit docs suitable for pushing to production use::

  make devsite-prod

Note that "production use" (and the staging target) are closely tied to the
Google documentation infrastructure, so it will be of very limited use outside
Google. Links to related documents here can be google.com specific. Production
mode contains devsite-specific templating and non-HTML constructs. The
``devsite-staging`` target is exactly the same except that the html pages are
all rooted under a folder called $USER, which allows each user to stage his own
copy of the docs.

When building in production mode you can specify the name of the subfolder in
which the docs are rooted by specifying ``SPHINXOPTS=-Ddevsite_foldername=``.
For example::

  make devsite-prod SPHINXOPTS=-Ddevsite_foldername=pepper_32

See https://sites.google.com/a/google.com/nativeclient/documents/how-to-update-developer-documentation#TOC-Staging-ReStructuredText-output-on-devsite
for more information on staging.

Local HTTP server to view the docs
----------------------------------

To view the HTML locally, build the docs with production mode turned off, and
run::

  make serve

This will start a webserver on the local machine, and allows the pages
to be viewed by in a browser by navigating to::

  http://localhost:8009/

Serving through a server and not just file:/// because this way the <link>
relative paths to CSS actually work.

Checking outgoing links for integrity
-------------------------------------

We use the Sphinx-provided link checker (configured in conf.py and with some
monkey-patching in the extension) to check the outgoing links from the
documentation. To run the link checker::

  make linkcheck

And look for "broken" in the output file.