1 | ********************** |
---|
2 | NEMO Quick Start Guide |
---|
3 | ********************** |
---|
4 | |
---|
5 | | The NEMO guide is made up of several files written in `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension), a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources. |
---|
6 | | You can view them one by one in plain text from `./source` folder, or export all to a user-friendly guide under `./build` (only HTML format at the moment, PDF expected later). |
---|
7 | |
---|
8 | Build and export the guide in HTML |
---|
9 | ================================== |
---|
10 | |
---|
11 | 1. Install Sphinx documentation generator, its BibTeX extension and "Read The Docs" theme thanks to `pip` packages tool |
---|
12 | |
---|
13 | .. code-block:: console |
---|
14 | |
---|
15 | $ pip install sphinx sphinxcontrib.bibtex sphinx_rtd_theme |
---|
16 | |
---|
17 | 2. Build the HTML export with `make` in `./build/html` |
---|
18 | |
---|
19 | .. code-block:: console |
---|
20 | |
---|
21 | $ make html |
---|
22 | |
---|
23 | 3. Finally browse the guide by opening `./build/html/NEMO_guide.html` |
---|
24 | |
---|
25 | |
---|
26 | Edit the sources and check the output in real time |
---|
27 | ================================================== |
---|
28 | |
---|
29 | | To facilitate the update of the guide, editors can install a useful package that will automatically trigger a new build and the reload of the HTML page for every recorded change in the sources. |
---|
30 | | So the reviewer saves time by controlling on-line their modifications almost as it types and also by avoiding repeated interactive rebuilds. |
---|
31 | |
---|
32 | Install `sphinx-autobuild` package |
---|
33 | |
---|
34 | .. code-block:: console |
---|
35 | |
---|
36 | $ pip install sphinx-autobuild |
---|
37 | |
---|
38 | Launch a local web server hosting a draft export of the guide (build this time in `./build/livehtml`) |
---|
39 | |
---|
40 | .. code-block:: console |
---|
41 | |
---|
42 | $ make livehtml |
---|
43 | |
---|
44 | | Open in the same time the 2 formats of the content to review: the source file and the web page by browsing from the new guide hosted by your local server on `<http://127.0.0.1:8000/NEMO_guide.html>`_. |
---|
45 | | Start the update, save your changes and verify instantly the HTML export in your browser. |
---|
46 | |
---|
47 | .. warning:: |
---|
48 | |
---|
49 | | Your modifications are not taken into account? |
---|
50 | | For symlink file, you will have to close it to update the HTML export. Otherwise look at the log of the Sphinx build, you probably made a typo! |
---|
51 | |
---|
52 | .. hint:: |
---|
53 | |
---|
54 | Are there broken links? Fix "Page not found" errors by running `make linkcheck` |
---|