Add the simple user guide: docs/guide.rst

Also update the README.rst a bit

2 files changed, 74 insertions, 11 deletions

diff --git a/README.rst b/README.rst
index 52aef30..c495b0a 100644
--- a/README.rst
+++ b/README.rst
@@ -36,11 +36,11 @@ Features
 
     Current supported point sources types:
 
-    - star-forming galaxies
-    - star-bursting galaxies
-    - radio-quiet AGNs
-    - Fanaroff-Riley type I (FRI) AGNs
-    - Fanaroff-Riley type II (FRII) AGNs
+    - Star-forming galaxies
+    - Star-bursting galaxies
+    - Radio-quiet AGNs
+    - Fanaroff-Riley type I (FR-I) AGNs
+    - Fanaroff-Riley type II (FR-II) AGNs
 
 * All-sky simulation
   (*Note:* partial-sky simulation not supported yet)
@@ -58,8 +58,7 @@ Requirements
 * `Python <https://www.python.org/>`_: >= 3.4
 * `CFITSIO <https://heasarc.gsfc.nasa.gov/fitsio/fitsio.html>`_
 * `HEALPix <http://healpix.sourceforge.net/>`_:
-  only the C++ library (e.g., package ``libhealpix-cxx0`` on Debian Linux)
-  required by `healpy <https://github.com/healpy/healpy>`_.
+  only the C++ library required by `healpy <https://github.com/healpy/healpy>`_.
 * `LLVM <http://llvm.org/>`_: = 3.8
   (required by `llvmlite <http://llvmlite.pydata.org/>`_ which is a
   dependency of `Numba <http://numba.pydata.org/>`_)
@@ -71,10 +70,10 @@ Installation
 
    $ git clone https://github.com/liweitianux/fg21sim
 
-2. Install the system requirements: CFITSIO, HEALPix, and LLVM.
+2. Install the above system requirements: CFITSIO, HEALPix, and LLVM.
 
 3. Install the required third-party Python packages.
-   And it is recommended to use the *virtual environment*::
+   And it is recommended to use the `virtual environment`_::
 
    $ cd fg21sim/
    $ make venv
@@ -87,13 +86,17 @@ Installation
 
    $ python3 setup.py install
 
-5. Great!  You are ready to use this package.
-   Just have a look, e.g.::
+5. You are ready to use this package. Just have a look, e.g.::
 
    $ fg21sim --help
    $ fg21sim-webui --help
 
 
+Documentations
+--------------
+To get started, read the `User Guide`_.
+
+
 Contributions
 -------------
 Great!  Be sure to consult the guidelines in |CONTRIBUTING.md|_.
@@ -127,12 +130,16 @@ Unless otherwise declared:
 
 .. |fg21sim| replace:: **fg21sim**
 .. _fg21sim: https://github.com/liweitianux/fg21sim
+.. _`User Guide`:
+   https://github.com/liweitianux/fg21sim/blob/master/docs/guide.rst
 .. |CONTRIBUTING.md| replace:: ``CONTRIBUTING.md``
 .. _CONTRIBUTING.md:
    https://github.com/liweitianux/fg21sim/blob/master/CONTRIBUTING.md
 .. |LICENSE-3RDPARTY| replace:: ``LICENSE-3RDPARTY``
 .. _LICENSE-3RDPARTY:
    https://github.com/liweitianux/fg21sim/blob/master/LICENSE-3RDPARTY
+.. _`virtual environment`:
+   https://docs.python.org/3/library/venv.html
 .. _`MIT License`: https://opensource.org/licenses/MIT
 .. _`Creative Commons Attribution 3.0 License`:
    https://creativecommons.org/licenses/by/3.0/us/deed.en_US
diff --git a/docs/guide.rst b/docs/guide.rst
new file mode 100644
index 0000000..e0f0536
--- /dev/null
+++ b/docs/guide.rst
@@ -0,0 +1,56 @@
+==========
+User Guide
+==========
+
+This is a simple guide on how to use the **fg21sim** package to carry
+out the foregrounds simulation, which produces the all-sky maps of the
+enabled foreground components.
+
+The simulation of several foreground components (e.g.,
+``galactic/synchrotron``, ``galactic/freefree``) uses the semi-empirical
+method, thus it requires specific template map(s) and/or
+observational/simulation catalog(s) as the input.
+
+* ``galactic/synchrotron``:
+  requires the Haslam 408 MHz survey as the template map, and the
+  spectral index map.
+* ``galactic/freefree``:
+  requires the Hα map and the dust map.
+* ``galactic/snr``:
+  requires the catalog of the Galactic SNRs.
+* ``extragalactic/clusters``:
+  requires the catalog of the clusters of galaxies.
+
+All the required input templates and catalogs can be retrieved using
+the ``fg21sim-download-data`` CLI tool, by providing it with this
+`data manifest <data-manifest.json>`_.
+
+Then, a configuration file is required to run the foregrounds simulation,
+which controls all aspects of the simulation behaviors.
+There are two types of configuration options:
+*required* (which require the user to explicitly provide the values)
+and *optional* (which already have sensible defaults, however, the user
+can also override them).
+
+There is an `example configuration file <fg21sim.conf.example>`_ with
+detailed explanations on each configuration option.
+Also there is a brief `test configuration file <fg21sim-test.conf>`_
+which may be useful to test whether this package is correctly installed
+and runs smoothly.
+
+Finally, the foregrounds simulation can be kicked off using the CLI tool::
+
+    $ fg21sim --logfile fg21sim.log fg21sim.conf
+
+This way, the simulation program will take configurations from
+file ``fg21sim.conf``, and log messages to both the screen and file
+``fg21sim.log``.
+
+
+On the other hand, the Web UI can also be used, which provides a more
+intuitive and friendly way to tune the configurations, to view the
+logging messages, as well as to navigate the simulation products::
+
+    $ fg21sim-webui --debug &
+
+Then the Web UI can be accessed at ``http://localhost:21127``.