Merge pull request #431 from AnrWang/patch-2

Modify content in `Contribute documentation`

docs/Contributing/ContributeDocs.rst

@@ -1,40 +1,42 @@
 Contribute documentation
 ============
 
-General procedure
+.. _general development procedure:
+
+General development procedure
 ~~~~~~~~~~~~~~~~~
 
-If you’re a more experienced with the abess and are looking forward to
+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.
+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
+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. - 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;
+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;
 
--  Clone your fork of abess to the local by
+2. Clone your fork of abess to the local by
    `Git <https://git-scm.com/>`__;
 
    .. code:: bash
 
-      $ git clone https://github.com/your_account_name/abess.git
+      $ git clone https://github.com/YourAccount/abess.git
       $ cd abess
 
--  Create a new branch, e.g. named ``my_branch``, to hold your
+3. Create a new branch, e.g. named ``docsdev``, to hold your
    development changes:
 
    .. code:: bash
 
-      $ git branch my_branch
-      $ git checkout my_branch
+      $ git branch docsdev
+      $ git checkout docsdev
 
-   It is preferred to work on your own branch instead of the master one;
+   Work on the ``docsdev`` branch for documentation development.
 
--  Commit your improvements or additions to documentation (forming an
+4. Commit your improvements and contribution to documentation (forming an
    ideally legible commit history):
 
    .. code:: bash
@@ -43,10 +45,10 @@ create a copy to your own GitHub account;
       $ git commit -m "some commits"
       $ git push
 
--  Merge your branch with the master branch that have the up-to-date
-   codes in `abess <https://github.com/abess-team/abess>`__;
+5.  Merge your branch with the master branch that have the up-to-date
+    codes in `abess <https://github.com/abess-team/abess>`__;
 
--  Submit a pull request explaining your contribution for documentation.
+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
@@ -58,7 +60,9 @@ 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.
+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
 ^^^^^^^^^^
@@ -73,7 +77,7 @@ parameters it requires, such as
 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 relies on
+The development of Python API's documentation relies on
 `Sphinx <https://pypi.org/project/Sphinx/>`__,
 `nbsphinx <https://pypi.org/project/nbsphinx/>`__ (support jupyter
 notebook for Sphinx),
@@ -83,22 +87,6 @@ markdown for Sphinx),
 (support “Read the Docs” theme for Sphinx). Make sure these packages
 have been installed.
 
-There are four basic steps to write documentation for the Python API:
-
-1. Add comments to Python files in ``python/abess`` directory.
-
-2. Go to the ``docs`` directory, and run ``make html`` in command line
-   to convert comments to ``.html`` files.
-
-3. Preview documentation by open/refresh the ``.html`` files in
-   ``docs/_build/Python-package/``.
-
-4. Repeat steps 1-3 until you are satisfied with the documentation for
-   Python API.
-
-More advanced topics for writing documentation are available at:
-`Sphinx <https://www.sphinx-doc.org/en/master/>`__.
-
 Tutorials
 ^^^^^^^^^
 
@@ -107,7 +95,7 @@ A tutorial is a long-form guide to some essential functions in the
 
 -  describes the problem that one function can solve;
 
--  show the reader how to solve with the function;
+-  show readers how to solve with the function;
 
 -  give more details about the potential advanced usage.
 
@@ -116,10 +104,39 @@ A typical online vignette example is present
 
 The development of the tutorial relies on `sphinix-gallery <https://pypi.org/project/sphinx-gallery/>`__.
 
-The development also follows the four basic steps for the Python API
-except the first step changes to:
+.. _python document development:
+
+Document development
+^^^^^^^^^
 
--  add/modify the tutorial files in ``docs/Tutorial`` directory.
+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
 ~~~~~~~~~~
@@ -173,7 +190,6 @@ There are also four steps to write online vignettes:
 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
+`pkgdown's
 website <https://pkgdown.r-lib.org/reference/build_home.html>`__ and
-`Hadley’s website <https://r-pkgs.org/vignettes.html>`__, respectively.
-
+`Hadley's website <https://r-pkgs.org/vignettes.html>`__, respectively.