Contribute documentation
========================

.. _general development procedure:

General development procedure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you're a more experienced with the ``abess`` and are looking forward to
improve your open source development skills, the next step up is to
contribute a pull request to a ``abess`` documentation.

In most of case, the workflow is given below. 
But if you are not familar with git and github, we suggest you install the `github
desktop <https://desktop.github.com/>`__ that provide a user-friendly
interaction interface for simplifying documentation contribution. 
You can fetch the documentation about Git `here <https://git-scm.com/>`__.

1. Fork the `master repository <https://github.com/abess-team/abess>`__ by clicking on the “Fork” button on the top right of the page, which would create a copy to your own GitHub account;

2. Clone your fork of abess to the local by
   `Git <https://git-scm.com/>`__;

   .. code:: bash

      $ git clone https://github.com/YourAccount/abess.git
      $ cd abess

3. Create a new branch, e.g. named ``docsdev``, to hold your
   development changes:

   .. code:: bash

      $ git branch docsdev
      $ git checkout docsdev

   Work on the ``docsdev`` branch for documentation development.

4. Commit your improvements and contribution to documentation (forming an
   ideally legible commit history):

   .. code:: bash

      $ git add changed_files
      $ git commit -m "some commits"
      $ git push

5.  Merge your branch with the master branch that have the up-to-date
    codes in `abess <https://github.com/abess-team/abess>`__;

6.  Submit a pull request explaining your contribution for documentation.

The `online documentation <https://abess.readthedocs.io>`__ for our
project are generated by generation by
`Sphinx <https://www.sphinx-doc.org/en/master/index.html>`__ and 
`sphinix-gallery <https://pypi.org/project/sphinx-gallery/>`__ for python and
`pkgdown <https://pkgdown.r-lib.org/index.html>`__ for R. 
Our website is published via `readthedocs <https://readthedocs.org>`__.

Python document
~~~~~~~~~~~~~~~

The Python document includes two parts. The first part depicts the APIs in ``abess``, and the second part aims to show simple use-cases and on-board new users.
After describing the two parts, we detailly explain the procedure for `python document development`_, 
which unfolds the Step 4 in `general development procedure`_.

Python API
^^^^^^^^^^

For the development of Python documentation, there is a little
difference between a new method and a new function. A new method need a
brief introduction and some examples, such as
`[link] <https://github.com/abess-team/abess/blob/master/python/abess/linear.py#:~:text=class%20abessLogistic(bess_base)%3A-,%22%22%22,%22%22%22,-def%20__init__(self)>`__;
and a new function under should at least contain an introduction and the
parameters it requires, such as
`[link] <https://github.com/abess-team/abess/blob/master/python/abess/linear.py#:~:text=return%20y-,def%20score(self%2C%20X%2C%20y)%3A,%22%22%22,-X%2C%20y%20%3D%20self>`__.
Also note that the style of Python document is similar to
`numpydoc <https://numpydoc.readthedocs.io/en/latest/format.html>`__.

The development of Python API's documentation mainly relies on
`Sphinx <https://pypi.org/project/Sphinx/>`__,
`sphinx-gallery <https://pypi.org/project/sphinx-gallery/>`__ (support
markdown for Sphinx),
`sphinx-rtd-theme <https://pypi.org/project/sphinx-rtd-theme/>`__
(support “Read the Docs” theme for Sphinx) and so on.

Please make sure all packages in :code:`docs/requirements.txt` 
have been installed.

Tutorials
^^^^^^^^^

A tutorial is a long-form guide to some essential functions in the
``abess`` package. We recommend to use a tutorial to:

-  describes the problem that one function can solve;

-  show readers how to solve with the function;

-  give more details about the potential advanced usage.

A typical online vignette example is present
`[here] <https://abess.readthedocs.io/en/latest/auto_gallery/1-glm/plot_1_LinearRegression.html>`__.

The development of the tutorial relies on `sphinix-gallery <https://pypi.org/project/sphinx-gallery/>`__.

.. _python document development:

Document development
^^^^^^^^^^^^^^^^^^^^

Before developing document, we presume that you have already complete the steps 1-3 described in `general development procedure`_, 
and you have installed necessary packages, including: ``sphinix-gallery``, ``Sphinx``, ``nbsphinx``, ``myst-parser``, ``sphinx-rtd-theme``.

There are five basic steps to write documentation for the Python document:

1. If you contributing a new document, please create a new ``.rst`` file in the ``docs/Python-package`` directory for describing APIs or ``docs/Tutorial`` for new Tutorials, 
   and write the documentation in the file. 
   If you would like to modify documents, please modify the corresponding ``.rst`` files in the ``docs`` directory.

2. Go to the ``docs`` directory (e.g., via ``cd docs``), 
   and convert ``.rst`` files to ``.html`` files by running the following command in the terminal:
   
   .. code:: bash

      $ make html
   
   and preview new documentation by opening/refreshing the ``index.html`` files in ``docs/_build/html`` directory.

3. Repeat step 1 and step 2 until you are satisfied with the documentation. 

4. If you use some packages in Pypi, please add these package into ``docs/requirements.txt`` 
   (for example, the ``geomstats`` package)
   so that the servers provided by `Readthedocs <https://readthedocs.org/>`__ pre-install these packages.
   
5. Submit a pull request from the ``docsdev`` branch in your repository ``YourAccount/abess`` 
   to the ``master`` branch in the repository ``abess-team/abess``.

More advanced topics for writing documentation are available at: `Sphinx <https://www.sphinx-doc.org/en/master/>`__.

R document
~~~~~~~~~~

The R document includes two parts. The first part depicts the APIs in the `abess` R package, and the second part aims to show simple use-cases and on-board new users.

R function
^^^^^^^^^^

For the development of R documentation, the most important thing to know
is that the abess R package relies on
`roxygen2 <https://cran.r-project.org/web/packages/roxygen2>`__ package.
This means that documentation is found in the R code close to the source
of each function. Before writing the documentation, it would be better
to ensure the usage of the `Rd
tags <https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html>`__.

There are four basic steps to write documentation for the R function in
abess:

1. Add comments to ``R`` files in ``R-package/R`` directory.

2. Run ``devtools::document()`` in R to convert roxygen comments to
   ``.Rd`` files.

3. Preview documentation with ``?``.

4. Repeat steps 1-3 until you are satisfied with the documentation.

More advanced topics for writing object documentation are available at:
https://r-pkgs.org/man.html.

Online vignette
^^^^^^^^^^^^^^^

The aim of a online R vignette is the same as a tutorial for Python
package. A typical online vignette example is presented in this
`[link] <https://abess-team.github.io/abess/articles/v03-classification.html>`__.
We strongly recommend to use R markdown (``.Rmd`` files) to organize a
online vignette.

There are also four steps to write online vignettes:

1. Add/modify to ``.Rmd`` files in ``R-package/vignettes`` directory.

2. Run ``pkgdown::build_articles()`` in R to convert ``.Rmd`` files to
   webpages. (Make sure the ``pkgdown`` R package has been installed.)

3. Preview the webpages.

4. Repeat steps 1-3 until you are satisfied with the vignettes.

You can learn many detail about ``pkgdown`` package and R markdown in
`pkgdown's
website <https://pkgdown.r-lib.org/reference/build_home.html>`__ and
`Hadley's website <https://r-pkgs.org/vignettes.html>`__, respectively.