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