| OLD | NEW |
| 1 nacl-docs-rst | 1 nacl-docs-rst |
| 2 ============= | 2 ============= |
| 3 | 3 |
| 4 Directory structure | 4 Directory structure |
| 5 ------------------- | 5 ------------------- |
| 6 | 6 |
| 7 This is a tree of .rst files that represent the source of the NaCl | 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: | 8 documentation. Some of the files and directories here are special: |
| 9 | 9 |
| 10 * conf.py: Sphinx configuration file | 10 * conf.py: Sphinx configuration file |
| 11 * images/: Images are stored here. Note that this isn't necessary - Sphinx | 11 * images/: Images are stored here. Note that this isn't necessary - Sphinx |
| 12 doesn't mind about interspersing images in .rst directories. | 12 doesn't mind about interspersing images in .rst directories. |
| 13 * _sphinxext/: Code of the Sphinx extension we use to generate HTML from .rst | 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 | 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 | 15 as part of the infrastructure - the real CSS comes from the real doc |
| 16 publishing server. | 16 publishing server. |
| 17 * _build/: Build artifacts (not checked into source control). | 17 * out/: Build artifacts (not checked into source control). |
| 18 * Makefile & README | 18 * Makefile & README |
| 19 | 19 |
| 20 How to build | 20 How to build |
| 21 ------------ | 21 ------------ |
| 22 | 22 |
| 23 To build the docs you will needs sphinx installed (and sphinx-build in your | 23 To build the docs you will needs sphinx installed (and sphinx-build in your |
| 24 path), and simply run: | 24 path), and simply run: |
| 25 | 25 |
| 26 make devsite | 26 make |
| 27 | 27 |
| 28 To rebuild all the pages always, add 'SPHINXOPTS=-a', e.g.: | 28 To rebuild all the pages always, add 'SPHINXOPTS=-a', e.g.: |
| 29 | 29 |
| 30 make SPHINXOPTS=-a devsite | 30 make SPHINXOPTS=-a |
| 31 | 31 |
| 32 To emit local-testing mode, instead of production mode, add: | 32 To emit local-testing mode, instead of production mode, add: |
| 33 SPHINXOPTS='-D devsite_production_mode=0' | 33 SPHINXOPTS='-D devsite_production_mode=0' |
| 34 e.g.: | 34 e.g.: |
| 35 | 35 |
| 36 make SPHINXOPTS='-D devsite_production_mode=0' devsite | 36 make SPHINXOPTS='-D devsite_production_mode=0' |
| 37 | 37 |
| 38 Production mode contains devsite-specific templating and non-HTML constructs. | 38 Production mode contains devsite-specific templating and non-HTML constructs. |
| 39 | 39 |
| 40 The builder prints out the value of this setting - make sure it's what you | 40 The builder prints out the value of this setting - make sure it's what you |
| 41 expect it to be. For example: | 41 expect it to be. For example: |
| 42 | 42 |
| 43 $ make devsite | 43 $ make |
| 44 sphinx-build -b devsite -d _build/doctrees . _build/devsite | 44 sphinx-build -b devsite -d out/doctrees . out/devsite |
| 45 Running Sphinx v1.2b1 | 45 Running Sphinx v1.2b1 |
| 46 loading pickled environment... done | 46 loading pickled environment... done |
| 47 ----> Devsite builder with production mode = 1 | 47 ----> Devsite builder with production mode = 1 |
| 48 | 48 |
| 49 Local HTTP server to view the docs | 49 Local HTTP server to view the docs |
| 50 ---------------------------------- | 50 ---------------------------------- |
| 51 | 51 |
| 52 To view the HTML locally, build the docs with production mode turned off, and | 52 To view the HTML locally, build the docs with production mode turned off, and |
| 53 run: | 53 run: |
| 54 | 54 |
| 55 make serve | 55 make serve |
| 56 | 56 |
| 57 This will start a webserver on the local machine, and allows the pages | 57 This will start a webserver on the local machine, and allows the pages |
| 58 to be viewed by in a browser by navigating to: | 58 to be viewed by in a browser by navigating to: |
| 59 | 59 |
| 60 http://localhost:8009/ | 60 http://localhost:8009/ |
| 61 | 61 |
| 62 Serving through a server and not just file:/// because this way the <link> | 62 Serving through a server and not just file:/// because this way the <link> |
| 63 relative paths to CSS actually work. | 63 relative paths to CSS actually work. |
| 64 | 64 |
| OLD | NEW |