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 * doxygen/: Contains scripts for building doxygen docs. 18 * Makefile & README 19 20 All output is written to native_client_sdk/doc_generated/... 21 22 How to build 23 ------------ 24 25 To build the docs you will need these debian/ubuntu packages: 26 27 * python-sphinx 28 * python-beautifulsoup 29 30 There are two primary make targets: ``chromesite`` and ``chromesite_rst``. The 31 ``chromesite`` target will build all documentation, including the doxygen docs. 32 This usually takes about a minute. To build this config, run:: 33 34 make 35 36 The ``chromesite_rst`` target will only build the ReST docs. This is usually 37 much faster. The default target is ``chromesite``. To build this config, run:: 38 39 make chromesite_rst 40 41 Local HTTP server to view the docs 42 ---------------------------------- 43 44 To view the HTML locally, build the docs with production mode turned off, and 45 run:: 46 47 make serve 48 49 This will start a webserver on the local machine, and allows the pages 50 to be viewed by in a browser by navigating to:: 51 52 http://localhost:8000/native-client 53 54 Serving through a server and not just file:/// because this way the <link> 55 relative paths to CSS actually work. 56 57 Checking outgoing links for integrity 58 ------------------------------------- 59 60 We use the Sphinx-provided link checker (configured in conf.py and with some 61 monkey-patching in the extension) to check the outgoing links from the 62 documentation. To run the link checker:: 63 64 make linkcheck 65 66 And look for "broken" in the output file. 67
