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.