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