[10990] | 1 | ********************** |
---|
| 2 | NEMO Quick Start Guide |
---|
| 3 | ********************** |
---|
| 4 | |
---|
[11707] | 5 | | The NEMO guide is made up of several files written in |
---|
| 6 | `ReStructuredText <http://docutils.sourceforge.net/rst.html>`_ (`.rst` extension), |
---|
| 7 | a WYSIWYG markup language used in the Python community, and scattered all over the NEMO sources. |
---|
[10990] | 8 | | 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). |
---|
| 9 | |
---|
| 10 | Build and export the guide in HTML |
---|
| 11 | ================================== |
---|
| 12 | |
---|
| 13 | 1. Install Sphinx documentation generator, its BibTeX extension and "Read The Docs" theme thanks to `pip` packages tool |
---|
| 14 | |
---|
| 15 | .. code-block:: console |
---|
| 16 | |
---|
| 17 | $ pip install sphinx sphinxcontrib.bibtex sphinx_rtd_theme |
---|
| 18 | |
---|
| 19 | 2. Build the HTML export with `make` in `./build/html` |
---|
| 20 | |
---|
| 21 | .. code-block:: console |
---|
| 22 | |
---|
| 23 | $ make html |
---|
| 24 | |
---|
| 25 | 3. Finally browse the guide by opening `./build/html/NEMO_guide.html` |
---|
| 26 | |
---|
| 27 | |
---|
| 28 | Edit the sources and check the output in real time |
---|
| 29 | ================================================== |
---|
| 30 | |
---|
| 31 | | 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. |
---|
| 32 | | So the reviewer saves time by controlling on-line their modifications almost as it types and also by avoiding repeated interactive rebuilds. |
---|
| 33 | |
---|
| 34 | Install `sphinx-autobuild` package |
---|
| 35 | |
---|
| 36 | .. code-block:: console |
---|
| 37 | |
---|
| 38 | $ pip install sphinx-autobuild |
---|
| 39 | |
---|
| 40 | Launch a local web server hosting a draft export of the guide (build this time in `./build/livehtml`) |
---|
| 41 | |
---|
| 42 | .. code-block:: console |
---|
| 43 | |
---|
| 44 | $ make livehtml |
---|
| 45 | |
---|
[10991] | 46 | | 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>`_. |
---|
[10990] | 47 | | Start the update, save your changes and verify instantly the HTML export in your browser. |
---|
| 48 | |
---|
| 49 | .. warning:: |
---|
| 50 | |
---|
| 51 | | Your modifications are not taken into account? |
---|
| 52 | | 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! |
---|
| 53 | |
---|
| 54 | .. hint:: |
---|
| 55 | |
---|
| 56 | Are there broken links? Fix "Page not found" errors by running `make linkcheck` |
---|