native_client_sdk/src/doc/README

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