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 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 relies on Sphinx, nbsphinx (support jupyter notebook for Sphinx), myst-parser (support markdown for Sphinx), sphinx-rtd-theme (support “Read the Docs” theme for Sphinx). Make sure these packages 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.