Cross Reference: /external/chromium_org/native_client_sdk/src/doc/

nacl-docs-rst
=============

Directory structure
-------------------

This is a tree of .rst files that represent the source of the NaCl
documentation. Some of the files and directories here are special:

* conf.py: Sphinx configuration file
* images/: Images are stored here. Note that this isn't necessary - Sphinx
  doesn't mind about interspersing images in .rst directories.
* _sphinxext/: Code of the Sphinx extension we use to generate HTML from .rst
* _static/: Static files, like CSS, for the documentation. This should be seen
  as part of the infrastructure - the real CSS comes from the real doc
  publishing server.
* doxygen/: Contains scripts for building doxygen docs.
* Makefile & README

All output is written to native_client_sdk/doc_generated/...

How to build
------------

To build the docs you will need these debian/ubuntu packages:

* python-sphinx
* python-beautifulsoup

There are two primary make targets: ``chromesite`` and ``chromesite_rst``. The
``chromesite`` target will build all documentation, including the doxygen docs.
This usually takes about a minute. To build this config, run::

  make

The ``chromesite_rst`` target will only build the ReST docs. This is usually
much faster. The default target is ``chromesite``. To build this config, run::

  make chromesite_rst

Local HTTP server to view the docs
----------------------------------

To view the HTML locally, build the docs with production mode turned off, and
run::

  make serve

This will start a webserver on the local machine, and allows the pages
to be viewed by in a browser by navigating to::

  http://localhost:8000/native-client

Serving through a server and not just file:/// because this way the <link>
relative paths to CSS actually work.

Checking outgoing links for integrity
-------------------------------------

We use the Sphinx-provided link checker (configured in conf.py and with some
monkey-patching in the extension) to check the outgoing links from the
documentation. To run the link checker::

  make linkcheck

And look for "broken" in the output file.
Name	Date	Size
..	02-Jul-2015	4 KiB
.gitignore	02-Jul-2015	7
_book.yaml	02-Jul-2015	3.6 KiB
_project.yaml	02-Jul-2015	152
_reference_toc.yaml	02-Jul-2015	23.7 KiB
_sphinxext/	02-Jul-2015	4 KiB
_static/	02-Jul-2015	4 KiB
c-api.rst	02-Jul-2015	51
community/	02-Jul-2015	4 KiB
conf.py	02-Jul-2015	5.9 KiB
cpp-api.rst	02-Jul-2015	55
devguide/	02-Jul-2015	4 KiB
doxygen/	02-Jul-2015	4 KiB
faq.rst	02-Jul-2015	26.2 KiB
glossary.rst	02-Jul-2015	2.3 KiB
help.rst	02-Jul-2015	2.5 KiB
image-list.rst	02-Jul-2015	1.5 KiB
images/	02-Jul-2015	4 KiB
index.rst	02-Jul-2015	4 KiB
io2014.rst	02-Jul-2015	7.6 KiB
Makefile	02-Jul-2015	2.8 KiB
nacl-and-pnacl.rst	02-Jul-2015	5.1 KiB
overview.rst	02-Jul-2015	11.8 KiB
OWNERS	02-Jul-2015	59
pepper_beta/	02-Jul-2015	4 KiB
pepper_dev/	02-Jul-2015	4 KiB
pepper_stable/	02-Jul-2015	4 KiB
PRESUBMIT.py	02-Jul-2015	1.1 KiB
publications-and-presentations.rst	02-Jul-2015	6.5 KiB
quick-start.rst	02-Jul-2015	1.1 KiB
README	02-Jul-2015	2 KiB
reference/	02-Jul-2015	4 KiB
rest-devsite-examples.rst	02-Jul-2015	5.7 KiB
sdk/	02-Jul-2015	4 KiB
sitemap.rst	02-Jul-2015	1.8 KiB
version.rst	02-Jul-2015	101