Writing documentation
############################################

SPhinX environment
*************************************************

.. note:: All the documentation generation operation should be in the directory of the ``docs``.

Install the dependencies
============================================

.. code-block:: shell

    pip install -r requirements.txt

Generate the ``html`` documentation
==============================================

Before generating the documentation, please check the output
path located at ``line 11`` in the ``make.bat`` file:

.. code-block:: shell

    set BUILDDIR=../../data-platform-website/build

.. warning:: Please pay attention to the extensions in the ``conf.py`` file, please comment ``"sphinx.ext.viewcode"`` if you do not want to make the source code open.

Generate the ``html`` file:

.. code-block:: shell

    make html


Tutorials
==================================================

- Cheatsheet: `https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_
- Official documentation: `https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
- Example: `NetworkX package <https://networkx.org/>`_

Documentation organization
*************************************************

Documentation is very important in the coding process, we should regard documentation as writing paper or report for what we have implemented in our codes.
A good organization could help readers understand better. In our
documentation, we have each folder for each chapter including:

* Introduction: very high-level documentation including some essential system flowcharts, feature introduciton, etc.
* Tutorial: walkthrough of the main functions including some essential instructions.
* Example: executable examples that are generated from ``jupyter notebook``.
* Reference: source codes, etc.
* Developer: for the developers.

With this organization, if you want to add a complete feature with
tutorial and examples, you should write an executable ``jupyternotebook`` and
add this page to the ``docs/example``, write a tutorial
in ``docs/tutorial`` while putting the source code in
``docs/reference``. To link the high-level tutorial and source code, you should add
essential internal links for the functions and classes.