Contribute documentation¶
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 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. 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
docsdev
branch 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.
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.
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¶
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 docs/requirements.txt
have been installed.
Tutorials¶
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.
Document development¶
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:
If you contributing a new document, please create a new
.rst
file in thedocs/Python-package
directory for describing APIs ordocs/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 thedocs
directory.Go to the
docs
directory (e.g., viacd docs
), and convert.rst
files to.html
files by running the following command in the terminal:$ make html
and preview new documentation by opening/refreshing the
index.html
files indocs/_build/html
directory.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, thegeomstats
package) so that the servers provided by Readthedocs pre-install these packages.Submit a pull request from the
docsdev
branch in your repositoryYourAccount/abess
to themaster
branch in the repositoryabess-team/abess
.
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¶
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
R
files inR-package/R
directory.Run
devtools::document()
in R to convert roxygen comments to.Rd
files.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.
Online vignette¶
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
[link].
We strongly recommend to use R markdown (.Rmd
files) to organize a
online vignette.
There are also four steps to write online vignettes:
Add/modify to
.Rmd
files inR-package/vignettes
directory.Run
pkgdown::build_articles()
in R to convert.Rmd
files to webpages. (Make sure thepkgdown
R 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
pkgdown's
website and
Hadley's website, respectively.