From 478700f04fe220374a0fbf928b8d10b1a0ccd0f7 Mon Sep 17 00:00:00 2001
From: AnrWang <104609978+AnrWang@users.noreply.github.com>
Date: Fri, 27 May 2022 12:47:17 +0800
Subject: [PATCH 1/7] Update ContributeDocs.rst
---
docs/Contributing/ContributeDocs.rst | 107 +++++++++++++++++++++------
1 file changed, 84 insertions(+), 23 deletions(-)
diff --git a/docs/Contributing/ContributeDocs.rst b/docs/Contributing/ContributeDocs.rst
index 755e5662b..2d04986b2 100644
--- a/docs/Contributing/ContributeDocs.rst
+++ b/docs/Contributing/ContributeDocs.rst
@@ -11,10 +11,9 @@ 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 `__ that provide a user-friendly
-interaction interface for simplifying documentation contribution. - Fork
-the `master repository `__ 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.
+
+- Fork the `master repository `__ 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
`Git `__;
@@ -83,22 +82,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 `__.
-
Tutorials
^^^^^^^^^
@@ -116,10 +99,88 @@ A typical online vignette example is present
The development of the tutorial relies on `sphinix-gallery `__.
-The development also follows the four basic steps for the Python API
-except the first step changes to:
+The development of Python document
+^^^^^^^^^
+
+There are three basic steps to write documentation for the Python document:
+
+1. Add comments to Python files
+
+You can refer to ``General procedure``, or do the following brief steps:
+
+- Fork the `master repository `__ as the same of the first steps of ``General procedure``;
+
+- Access in ``your_account_name/abess``, then click on the “master” button and create a new branch, e.g. named ``my_branch``. Upload files in the suitable directory.
+
+If you use packages that aren't base packages in your comments, please add them in ``docs/requirements.txt`` to make the cloud server running with the packages correctly.
+
+2. Preview documentation
+
+In this step, packages `virtualenv `__ is required to create isolated Python environments. Make sure the package have been installed.
+
+- Choose a local directory you prefer then create isolated Python environments. Run the
+ following code in command line:
+
+ .. code:: bash
+
+ $ cd directory_you_prefer
+ $ virtualenv env_name
+
+ "env_name" is the name of the virtual environment directory, and
+ you can customize the name;
+
+- Activate the virtual environment, and "cd" to ``env_name\Scripts`` directory:
+
+ - Under windows:
+
+ .. code:: bash
+
+ $ cd env_name\Scripts
+ $ .\activate
+
+ If you get error when running ``.\activate``, Run the following code then enter "y" before running ``.\activate``:
+
+ .. code:: bash
+
+ $ set-executionpolicy remotesigned
+
+ - Under Mac:
+
+ .. code:: bash
+
+ $ source env_name/bin/activate
+ $ cd env_name\Scripts
+
+- Clone your fork of abess to ``env_name\Scripts`` directory. If you have already clone it, just copy it here.
+
+ Run the following code in in command line or git:
+
+ .. code:: bash
+
+ $ git clone https://github.com/your_account_name/abess.git
+
+ Or run the following code to clone the new branch:
+
+ .. code:: bash
+
+ $ git clone -b my_branch https://github.com/your_account_name/abess.git
+
+ You can also clone it from the `github desktop `__ ;
+
+- "cd" to ``abess\docs`` directory, then convert comments to ``.html`` files:
+
+ .. code:: bash
+
+ $ cd abess\docs
+ $ .\make html
+
+- Preview documentation by open/refresh the ``.html`` files in ``docs/_build/html`` directory.
+
+3. Submit a pull request
+
+Repeat steps 1-2 until you are satisfied with the documentation. Then submit a pull request from ``my_branch`` to ``abess-team/abess``.
-- add/modify the tutorial files in ``docs/Tutorial`` directory.
+More advanced topics for writing documentation are available at: `Sphinx `__.
R document
~~~~~~~~~~
From dbac54a3fa2080d866fafd26d5e71cc34c05d825 Mon Sep 17 00:00:00 2001
From: AnrWang <104609978+AnrWang@users.noreply.github.com>
Date: Fri, 27 May 2022 12:50:27 +0800
Subject: [PATCH 2/7] Update ContributeDocs.rst
---
docs/Contributing/ContributeDocs.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/Contributing/ContributeDocs.rst b/docs/Contributing/ContributeDocs.rst
index 2d04986b2..39159aaea 100644
--- a/docs/Contributing/ContributeDocs.rst
+++ b/docs/Contributing/ContributeDocs.rst
@@ -178,7 +178,7 @@ In this step, packages `virtualenv `__ is r
3. Submit a pull request
-Repeat steps 1-2 until you are satisfied with the documentation. Then submit a pull request from ``my_branch`` to ``abess-team/abess``.
+Repeat steps 1-2 until you are satisfied with the documentation. Then submit a pull request from ``your_account_name/abess`` ``my_branch`` to ``abess-team/abess`` ``master``.
More advanced topics for writing documentation are available at: `Sphinx `__.
From ea4238864f318db45645f9bb1a859e9faf4ebdd1 Mon Sep 17 00:00:00 2001
From: AnrWang <104609978+AnrWang@users.noreply.github.com>
Date: Fri, 27 May 2022 17:15:51 +0800
Subject: [PATCH 3/7] Update ContributeDocs.rst
---
docs/Contributing/ContributeDocs.rst | 37 ++++++++++++----------------
1 file changed, 16 insertions(+), 21 deletions(-)
diff --git a/docs/Contributing/ContributeDocs.rst b/docs/Contributing/ContributeDocs.rst
index 39159aaea..afdc24205 100644
--- a/docs/Contributing/ContributeDocs.rst
+++ b/docs/Contributing/ContributeDocs.rst
@@ -106,30 +106,30 @@ There are three basic steps to write documentation for the Python document:
1. Add comments to Python files
-You can refer to ``General procedure``, or do the following brief steps:
+You can refer to ``General procedure``, or follow the simple steps below:
-- Fork the `master repository `__ as the same of the first steps of ``General procedure``;
+- Fork the `master repository `__ according to the first step of ``General procedure``;
-- Access in ``your_account_name/abess``, then click on the “master” button and create a new branch, e.g. named ``my_branch``. Upload files in the suitable directory.
+- Access in ``your_account_name/abess``, then click “master” and create a new branch, e.g. named ``my_branch``. Upload files to the suitable directory.
-If you use packages that aren't base packages in your comments, please add them in ``docs/requirements.txt`` to make the cloud server running with the packages correctly.
+If you’re using packages that aren't basic ones in your comments, paste their names into ``docs/requirements.txt`` so that the cloud server can run the packages correctly.
2. Preview documentation
-In this step, packages `virtualenv `__ is required to create isolated Python environments. Make sure the package have been installed.
+In this step, package `virtualenv `__ is required to create isolated Python environments. Please make sure the package is installed in advance.
-- Choose a local directory you prefer then create isolated Python environments. Run the
- following code in command line:
+- Choose a local directory you prefer, then create isolated Python environments. Run the
+ following codes in command line:
.. code:: bash
$ cd directory_you_prefer
$ virtualenv env_name
- "env_name" is the name of the virtual environment directory, and
- you can customize the name;
+ "env_name" is the name of the virtual environment directory which
+ you can customize;
-- Activate the virtual environment, and "cd" to ``env_name\Scripts`` directory:
+- Activate the virtual environment, and change directory to ``env_name\Scripts``:
- Under windows:
@@ -138,7 +138,7 @@ In this step, packages `virtualenv `__ is r
$ cd env_name\Scripts
$ .\activate
- If you get error when running ``.\activate``, Run the following code then enter "y" before running ``.\activate``:
+ If you come into error when running ``.\activate``, Run the following code and enter "y" before running ``.\activate``:
.. code:: bash
@@ -151,9 +151,9 @@ In this step, packages `virtualenv `__ is r
$ source env_name/bin/activate
$ cd env_name\Scripts
-- Clone your fork of abess to ``env_name\Scripts`` directory. If you have already clone it, just copy it here.
+- Clone your fork of abess to ``env_name\Scripts`` directory. If you have already cloned it, just copy it here.
- Run the following code in in command line or git:
+ Run the following code in command line or git:
.. code:: bash
@@ -167,26 +167,21 @@ In this step, packages `virtualenv `__ is r
You can also clone it from the `github desktop `__ ;
-- "cd" to ``abess\docs`` directory, then convert comments to ``.html`` files:
+- Change directory to ``abess\docs``, then convert comments to ``.html`` files:
.. code:: bash
$ cd abess\docs
$ .\make html
-- Preview documentation by open/refresh the ``.html`` files in ``docs/_build/html`` directory.
+- Preview documentation by opening/refreshing the ``.html`` files in ``docs/_build/html`` directory.
3. Submit a pull request
-Repeat steps 1-2 until you are satisfied with the documentation. Then submit a pull request from ``your_account_name/abess`` ``my_branch`` to ``abess-team/abess`` ``master``.
+Repeat step 1 and step 2 until you are satisfied with the documentation. Then submit a pull request from ``your_account_name/abess`` ``my_branch`` to ``abess-team/abess`` ``master``.
More advanced topics for writing documentation are available at: `Sphinx `__.
-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
^^^^^^^^^^
From 0167e246d793fe905ca22903745266cd848731d4 Mon Sep 17 00:00:00 2001
From: AnrWang <104609978+AnrWang@users.noreply.github.com>
Date: Fri, 27 May 2022 17:24:55 +0800
Subject: [PATCH 4/7] Update ContributeDocs.rst
---
docs/Contributing/ContributeDocs.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/Contributing/ContributeDocs.rst b/docs/Contributing/ContributeDocs.rst
index afdc24205..c3c27efd9 100644
--- a/docs/Contributing/ContributeDocs.rst
+++ b/docs/Contributing/ContributeDocs.rst
@@ -99,7 +99,7 @@ A typical online vignette example is present
The development of the tutorial relies on `sphinix-gallery `__.
-The development of Python document
+The development of python document
^^^^^^^^^
There are three basic steps to write documentation for the Python document:
From 5748d65bb7fa2bcda729d5696a9378893d154166 Mon Sep 17 00:00:00 2001
From: AnrWang <104609978+AnrWang@users.noreply.github.com>
Date: Fri, 27 May 2022 17:35:15 +0800
Subject: [PATCH 5/7] Update ContributeDocs.rst
---
docs/Contributing/ContributeDocs.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/Contributing/ContributeDocs.rst b/docs/Contributing/ContributeDocs.rst
index c3c27efd9..e9d13cc8c 100644
--- a/docs/Contributing/ContributeDocs.rst
+++ b/docs/Contributing/ContributeDocs.rst
@@ -99,7 +99,7 @@ A typical online vignette example is present
The development of the tutorial relies on `sphinix-gallery `__.
-The development of python document
+Development
^^^^^^^^^
There are three basic steps to write documentation for the Python document:
From 0ff811384d8f66cca4f1f07304f97b187b254763 Mon Sep 17 00:00:00 2001
From: AnrWang <104609978+AnrWang@users.noreply.github.com>
Date: Fri, 27 May 2022 20:16:22 +0800
Subject: [PATCH 6/7] Update ContributeDocs.rst
---
docs/Contributing/ContributeDocs.rst | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/docs/Contributing/ContributeDocs.rst b/docs/Contributing/ContributeDocs.rst
index e9d13cc8c..004057f26 100644
--- a/docs/Contributing/ContributeDocs.rst
+++ b/docs/Contributing/ContributeDocs.rst
@@ -182,6 +182,11 @@ Repeat step 1 and step 2 until you are satisfied with the documentation. Then su
More advanced topics for writing documentation are available at: `Sphinx `__.
+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
^^^^^^^^^^
From 72ab2fe723e8b7da42b3517ee10919c4a9b560bc Mon Sep 17 00:00:00 2001
From: AnrWang <104609978+AnrWang@users.noreply.github.com>
Date: Sun, 29 May 2022 10:09:24 +0800
Subject: [PATCH 7/7] Update ContributeDocs.rst
---
docs/Contributing/ContributeDocs.rst | 139 +++++++++------------------
1 file changed, 47 insertions(+), 92 deletions(-)
diff --git a/docs/Contributing/ContributeDocs.rst b/docs/Contributing/ContributeDocs.rst
index 004057f26..eace90e63 100644
--- a/docs/Contributing/ContributeDocs.rst
+++ b/docs/Contributing/ContributeDocs.rst
@@ -1,39 +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 `__ that provide a user-friendly
interaction interface for simplifying documentation contribution.
+You can fetch the documentation about Git `here `__.
-- Fork the `master repository `__ by clicking on the “Fork” button on the top right of the page, which would create a copy to your own GitHub account;
+1. Fork the `master repository `__ 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 `__;
.. 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
@@ -42,10 +45,10 @@ interaction interface for simplifying documentation contribution.
$ git commit -m "some commits"
$ git push
-- Merge your branch with the master branch that have the up-to-date
- codes in `abess `__;
+5. Merge your branch with the master branch that have the up-to-date
+ codes in `abess `__;
-- Submit a pull request explaining your contribution for documentation.
+6. Submit a pull request explaining your contribution for documentation.
The `online documentation `__ for our
project are generated by generation by
@@ -57,7 +60,9 @@ Our website is published via `readthedocs `__.
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
^^^^^^^^^^
@@ -72,7 +77,7 @@ parameters it requires, such as
Also note that the style of Python document is similar to
`numpydoc `__.
-The development of Python API’s documentation relies on
+The development of Python API's documentation relies on
`Sphinx `__,
`nbsphinx `__ (support jupyter
notebook for Sphinx),
@@ -90,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.
@@ -99,86 +104,37 @@ A typical online vignette example is present
The development of the tutorial relies on `sphinix-gallery `__.
-Development
-^^^^^^^^^
-
-There are three basic steps to write documentation for the Python document:
-
-1. Add comments to Python files
-
-You can refer to ``General procedure``, or follow the simple steps below:
-
-- Fork the `master repository `__ according to the first step of ``General procedure``;
-
-- Access in ``your_account_name/abess``, then click “master” and create a new branch, e.g. named ``my_branch``. Upload files to the suitable directory.
-
-If you’re using packages that aren't basic ones in your comments, paste their names into ``docs/requirements.txt`` so that the cloud server can run the packages correctly.
-
-2. Preview documentation
-
-In this step, package `virtualenv `__ is required to create isolated Python environments. Please make sure the package is installed in advance.
+.. _python document development:
-- Choose a local directory you prefer, then create isolated Python environments. Run the
- following codes in command line:
-
- .. code:: bash
+Document development
+^^^^^^^^^
- $ cd directory_you_prefer
- $ virtualenv env_name
-
- "env_name" is the name of the virtual environment directory which
- you can customize;
+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``.
-- Activate the virtual environment, and change directory to ``env_name\Scripts``:
-
- - Under windows:
-
- .. code:: bash
+There are five basic steps to write documentation for the Python document:
- $ cd env_name\Scripts
- $ .\activate
-
- If you come into error when running ``.\activate``, Run the following code and enter "y" before running ``.\activate``:
-
- .. code:: bash
+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.
- $ set-executionpolicy remotesigned
-
- - Under Mac:
+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
-
- $ source env_name/bin/activate
- $ cd env_name\Scripts
-
-- Clone your fork of abess to ``env_name\Scripts`` directory. If you have already cloned it, just copy it here.
-
- Run the following code in command line or git:
-
- .. code:: bash
-
- $ git clone https://github.com/your_account_name/abess.git
-
- Or run the following code to clone the new branch:
-
- .. code:: bash
+ .. code:: bash
- $ git clone -b my_branch https://github.com/your_account_name/abess.git
+ $ make html
- You can also clone it from the `github desktop `__ ;
-
-- Change directory to ``abess\docs``, then convert comments to ``.html`` files:
-
- .. code:: bash
-
- $ cd abess\docs
- $ .\make html
-
-- Preview documentation by opening/refreshing the ``.html`` files in ``docs/_build/html`` directory.
+ and preview new documentation by opening/refreshing the ``index.html`` files in ``docs/_build/html`` directory.
-3. Submit a pull request
+3. Repeat step 1 and step 2 until you are satisfied with the documentation.
-Repeat step 1 and step 2 until you are satisfied with the documentation. Then submit a pull request from ``your_account_name/abess`` ``my_branch`` to ``abess-team/abess`` ``master``.
+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 `__ 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 `__.
@@ -234,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 `__ and
-`Hadley’s website `__, respectively.
-
+`Hadley's website `__, respectively.