1nacl-docs-rst 2============= 3 4Directory structure 5------------------- 6 7This is a tree of .rst files that represent the source of the NaCl 8documentation. Some of the files and directories here are special: 9 10* conf.py: Sphinx configuration file 11* images/: Images are stored here. Note that this isn't necessary - Sphinx 12 doesn't mind about interspersing images in .rst directories. 13* _sphinxext/: Code of the Sphinx extension we use to generate HTML from .rst 14* _static/: Static files, like CSS, for the documentation. This should be seen 15 as part of the infrastructure - the real CSS comes from the real doc 16 publishing server. 17* _build/: Build artifacts (not checked into source control). 18* Makefile & README 19 20How to build 21------------ 22 23To build the docs you will needs sphinx installed (and sphinx-build in your 24path). On debian/ubuntu this command is part of the ``python-sphinx`` package. 25 26There are many different output formats that can be generated using the targets 27in the included Makefile. The three most commonly used ones are ``devsite``, 28``devsite-prod`` and ``devsite-staging``. 29 30The ``devsite`` configuration is for generating docs for local viewing and is 31also the default make target. To build this config simply run:: 32 33 make 34 35To rebuild all the pages always, add ``SPHINXOPTS=-a``, e.g.:: 36 37 make SPHINXOPTS=-a 38 39To emit docs suitable for pushing to production use:: 40 41 make devsite-prod 42 43Note that "production use" (and the staging target) are closely tied to the 44Google documentation infrastructure, so it will be of very limited use outside 45Google. Links to related documents here can be google.com specific. Production 46mode contains devsite-specific templating and non-HTML constructs. The 47``devsite-staging`` target is exactly the same except that the html pages are 48all rooted under a folder called $USER, which allows each user to stage his own 49copy of the docs. 50 51When building in production mode you can specify the name of the subfolder in 52which the docs are rooted by specifying ``SPHINXOPTS=-Ddevsite_foldername=``. 53For example:: 54 55 make devsite-prod SPHINXOPTS=-Ddevsite_foldername=pepper_32 56 57See https://sites.google.com/a/google.com/nativeclient/documents/how-to-update-developer-documentation#TOC-Staging-ReStructuredText-output-on-devsite 58for more information on staging. 59 60Local HTTP server to view the docs 61---------------------------------- 62 63To view the HTML locally, build the docs with production mode turned off, and 64run:: 65 66 make serve 67 68This will start a webserver on the local machine, and allows the pages 69to be viewed by in a browser by navigating to:: 70 71 http://localhost:8009/ 72 73Serving through a server and not just file:/// because this way the <link> 74relative paths to CSS actually work. 75 76Checking outgoing links for integrity 77------------------------------------- 78 79We use the Sphinx-provided link checker (configured in conf.py and with some 80monkey-patching in the extension) to check the outgoing links from the 81documentation. To run the link checker:: 82 83 make linkcheck 84 85And look for "broken" in the output file. 86