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.