Skip to content

Documentation

Documentation

Documentation of OpenML consists of the general information pages, such as these, that include common concepts. Additionally, each software package such as the Python, Java, and R connectors has their own documentation. For convenience, those documentation pages are also available through this common documentation portal.

We always value contributions to our documentation. 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.

Below you can find more information about how each set of documentation pages is built.

General Documentation

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.

To build the documentation locally, first make sure all dependencies specified in requirements.txt are installed:

1
2
3
4
python -m venv .venv
source .venv/bin/activate
python -m pip install uv
uv pip install -r requirements.txt

After installing the dependencies, run mkdocs serve -f mkdocs-local.yml in the top directory (with the mkdocs.yml file). Any changes made after that will be hot-loaded.

To build the full documentation, including importing the documentation from other repositories, run mkdocs serve in the top directory (with the mkdocs.yml file). This can take a while to compile, so only use this when needed. You might also need to set export NUMPY_EXPERIMENTAL_DTYPE_API=1 (or set NUMPY_EXPERIMENTAL_DTYPE_API=1 on Windows).

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.

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.