source: NEMO/trunk/doc/rst/README.rst @ 10990

Last change on this file since 10990 was 10990, checked in by nicolasmartin, 2 years ago

Global review of the building and editing operations on NEMO guide

  • Addition of README.rst for users and editors
  • Waiver of the use of requirements_* files for the installation of Python dependencies, instead run the following commands
    • pip install sphinx sphinxcontrib.bibtex sphinx_rtd_theme for building and offline editing (make html )
    • pip install sphinx-autobuild for online editing on local server (make htmllive)
  • Put offline and online editing builds in distinct folders to prevent confusion and provide a backup for comparison
    • make html ./build/html
    • make htmllive./build/htmllive
  • Fix a coding issue in conf.py to display a clean revision number

Due to the state of the forge server (deprecated Python 3 library),
the guide builded internally does not have the expected rendering and
thus can not be made available to users in this version.
As a consequence, the online version of the guide will be updated upon request and
imported from a external build.

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 `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
8Build and export the guide in HTML
9==================================
10
111.  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
172.  Build the HTML export with `make` in `./build/html`
18
19    .. code-block:: console
20
21        $ make html
22
233.  Finally browse the guide by opening `./build/html/NEMO_guide.html`
24
25
26Edit 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
32Install `sphinx-autobuild` package
33
34.. code-block:: console
35
36   $ pip install sphinx-autobuild
37
38Launch 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| In the same time, open 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 <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`
Note: See TracBrowser for help on using the repository browser.