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 |