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.

  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;

  2. Clone your fork of abess to the local by Git;

    $ git clone https://github.com/YourAccount/abess.git
    $ cd abess
    
  3. 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.

  4. Commit your improvements and contribution to documentation (forming an ideally legible commit history):

    $ git add changed_files
    $ git commit -m "some commits"
    $ git push
    
  5. Merge your branch with the master branch that have the up-to-date codes in abess;

  6. 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:

  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.

  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:

    $ make html
    

    and preview new documentation by opening/refreshing the index.html files in docs/_build/html directory.

  3. Repeat step 1 and step 2 until you are satisfied with the documentation.

  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.

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:

  1. Add comments to R files in R-package/R directory.

  2. Run devtools::document() in R to convert roxygen comments to .Rd files.

  3. Preview documentation with ?.

  4. 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:

  1. Add/modify to .Rmd files in R-package/vignettes directory.

  2. Run pkgdown::build_articles() in R to convert .Rmd files to webpages. (Make sure the pkgdown R package has been installed.)

  3. Preview the webpages.

  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 website and Hadley's website, respectively.