Documentation

General Documentation

High-quality and up-to-date documentation are crucial. If you notice any mistake in these documentation pages, click the button (on the top right). It will open up an editing page on GitHub (you do need to be logged in). 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.

OpenML is a big project with multiple repositories. To keep the documentation close to the code, it will always be kept in the relevant repositories (see below), and combined into these documentation pages using MkDocs multirepo.

Developer note

To work on the documentation locally, do the following:

git clone https://github.com/openml/docs.git
pip install -r requirements.txt

To build the documentation, run mkdocs serve in the top directory (with the mkdocs.yml file). Any changes made after that will be hot-loaded.

The documentation will be auto-deployed with every push or merge with the master branch of https://www.github.com/openml/docs/. In the background, a CI job will run mkdocs gh-deploy, which will build the HTML files and push them to the gh-pages branch of openml/docs. https://docs.openml.org is just a reverse proxy for https://openml.github.io/docs/.

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.

Developer note

A CircleCI job will automatically render the documentation on every GitHub commit, using Sphinx. For inclusion in these documentation pages, it will also be rendered in markdown and imported.

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.

Developer note

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.

• Javadocs: https://www.openml.org/docs/

Developer note

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

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.