src/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 * _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.