Skip to content

Editing Documentation

General Documentation

The general documentation (the one you are reading now) in written in MarkDown, can be easily edited by clicking the edit button (the pencil icon) on the top of every page. It will open up an editing page on GitHub (you do need to be logged in on GitHub). When you are done, add a small message explaining the change and click 'commit changes'. On the next page, just launch the pull request. We will then review it and approve the changes, or discuss them if necessary.

The sources are generated by MkDocs, using the Material theme. Check these docs to see what is possible in terms of styling.

Note

Developers: To deploy the documentation, you need to have MkDocs and MkDocs-Material installed, and then run mkdocs gh-deploy in the docs directory (with the mkdocs.yml file). This will build the HTML files and push them to the gh-pages branch of openml/OpenML. https://docs.openml.org is just a reverse proxy for https://openml.github.io/OpenML/.

REST API

The REST API is documented using Swagger.io, in YAML. This generates a nice web interface that also allows trying out the API calls using your own API key (when you are logged in).

You can edit the sources on SwaggerHub. When you are done, export to json and replace the downloads/swagger.json file in the OpenML main GitHub repository. You need to do a pull request that is then reviewed by us. When we merge the new file the changes are immediately available.

The data API can be edited in the same way.

Python API

To edit the tutorial, you have to edit the reStructuredText files on openml-python/doc. When done, you can do a pull request.

To edit the documentation of the python functions, edit the docstrings in the Python code. When done, you can do a pull request.

Note

Developers: A CircleCI job will automatically render the documentation on every GitHub commit, using Sphinx.

R API

To edit the tutorial, you have to edit the Rmarkdown files on openml-r/vignettes.

To edit the documentation of the R functions, edit the Roxygen documention next to the functions in the R code.

Note

Developers: A Travis job will automatically render the documentation on every GitHub commit, using knitr. The Roxygen documentation is updated every time a new version is released on CRAN.

Java API

The Java Tutorial is written in markdown and can be edited the usual way (see above).

To edit the documentation of the Java functions, edit the documentation next to the functions in the Java code.

Note

Developers: A Travis job will automatically render the documentation on every GitHub commit, using Javadoc.