source: NEMO/branches/2019/ENHANCE-03_closea/doc/rst/README.rst @ 13108

Last change on this file since 13108 was 12149, checked in by ayoung, 20 months ago

Updated trunk to 12072

File size: 2.2 KB
Line 
1**********************
2NEMO Quick Start Guide
3**********************
4
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.
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
10Build and export the guide in HTML
11==================================
12
131.  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
192.  Build the HTML export with `make` in `./build/html`
20
21    .. code-block:: console
22
23        $ make html
24
253.  Finally browse the guide by opening `./build/html/NEMO_guide.html`
26
27
28Edit 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
34Install `sphinx-autobuild` package
35
36.. code-block:: console
37
38   $ pip install sphinx-autobuild
39
40Launch 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
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>`_.
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`
Note: See TracBrowser for help on using the repository browser.