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 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.