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
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;
Clone your fork of abess to the local by Git;
$ git clone https://github.com/YourAccount/abess.git $ cd abess
Create a new branch, e.g. named
docsdev, to hold your development changes:
$ git branch docsdev $ git checkout docsdev
Work on the
docsdevbranch for documentation development.
Commit your improvements and contribution to documentation (forming an ideally legible commit history):
$ git add changed_files $ git commit -m "some commits" $ git push
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.
The online documentation for our project are generated by generation by Sphinx and sphinix-gallery for python and pkgdown for R. Our website is published via readthedocs.
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.
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]; and a new function under should at least contain an introduction and the parameters it requires, such as [link]. Also note that the style of Python document is similar to numpydoc.
The development of Python API's documentation mainly relies on Sphinx, sphinx-gallery (support markdown for Sphinx), sphinx-rtd-theme (support “Read the Docs” theme for Sphinx) and so on.
Please make sure all packages in
have been installed.
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].
The development of the tutorial relies on sphinix-gallery.
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:
There are five basic steps to write documentation for the Python document:
If you contributing a new document, please create a new
.rstfile in the
docs/Python-packagedirectory for describing APIs or
docs/Tutorialfor new Tutorials, and write the documentation in the file. If you would like to modify documents, please modify the corresponding
.rstfiles in the
Go to the
docsdirectory (e.g., via
cd docs), and convert
.htmlfiles by running the following command in the terminal:
$ make html
and preview new documentation by opening/refreshing the
Repeat step 1 and step 2 until you are satisfied with the documentation.
If you use some packages in Pypi, please add these package into
docs/requirements.txt(for example, the
geomstatspackage) so that the servers provided by Readthedocs pre-install these packages.
Submit a pull request from the
docsdevbranch in your repository
masterbranch in the repository
More advanced topics for writing documentation are available at: Sphinx.
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.
For the development of R documentation, the most important thing to know is that the abess R package relies on 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.
There are four basic steps to write documentation for the R function in abess:
Add comments to
devtools::document()in R to convert roxygen comments to
Preview documentation with
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.
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
We strongly recommend to use R markdown (
.Rmd files) to organize a
There are also four steps to write online vignettes:
pkgdown::build_articles()in R to convert
.Rmdfiles to webpages. (Make sure the
pkgdownR package has been installed.)
Preview the webpages.
Repeat steps 1-3 until you are satisfied with the vignettes.
You can learn many detail about
pkgdown package and R markdown in
Hadley's website, respectively.