Extending the Documentation

Syne Tune comes with an extensive amount of documentation:

  • User-facing APIs are commented in the code, using the reStructered text format. This is used to generate the API Reference. Please refer to the code in order to understand our conventions. Please make sure that links to classes, methods, or functions work. In the presence of :math: expression, the docstring should be raw: r""" ... """.

  • Examples in examples/ are working, documented scripts showcasing individual features. If you contribute a new example, please also link it in docs/source/examples.rst.

  • Frequently asked questions at docs/source/faq.rst.

  • Table of all HPO algorithms in docs/source/getting_started.rst. If you contribute a new HPO method, please add a row there. As explained above, please also extend baselines.

  • Tutorials at docs/source/tutorials/. These are short chapters, explaining a concept in more detail than an example. A tutorial should be self-contained and come with functioning code, which can be run in a reasonable amount of time and cost. It may contain figures created with a larger effort.

Building the Documentation

You can build the documentation locally as follows. Make sure to have Syne Tune installed with dev dependencies:

cd docs
rm -rf source/_apidoc
make clean
make html

Then, open docs/build/html/index.html in your browser.

The documentation is also built as part of our CI system, so you can inspect it as part of a pull request:

  • Move to the list of all checks (if the PR is in good shape, you should see All checks have passed)

  • Locate docs/readthedocs.org:syne-tune at the end of the list. Click on Details

  • Click on View docs just below Build took X seconds (do not click on the tall View Docs button upper right, this leads to the latest public docs)

When extending the documentation, please verify the following:

  • Check whether links work. They typically fail silently, possibly emitting a warning. Use proper links when referring to classes, modules, functions, methods, or constants, and check whether the links to the API Reference work.

Conventions

We use the following conventions to ensure that documentation stays up-to-date:

  • Use literalinclude for almost all code snippets. In general, the documentation is showing code which is part of a functional script, which can either be in examples/, in benchmarking/examples/, or otherwise next to the documentation files.

  • Almost all code shown in the documentation is run as part of integration testing (.github/workflows/integ-tests.yml) or end-to-end testing (.github/workflows/end-to-end-tests.yml). If you contribute documentation with code, please insert your functional script into one of the two:

    • integ-tests.yml is run as part of our CI system. Code should run for no more than 30 seconds. It must not depend on data loaded from elsewhere, and not make use of surrogate blackboxes. It must not use SageMaker.

    • end-to-end-tests.yml is run manually on a regular basis, and in particular before a new release. Code may download files or depend on surrogate blackboxes. It may use SageMaker. Costs and runtime should be kept reasonable.

  • Links to other parts of the documentation should be used frequently. We use anonymous references (two trailing underscores).

  • Whenever mentioning a code construction (class, method, function, module, constant), please use a proper link with absolute module name and leading tilde. This allows interested readers to inspect API details and the code. When the same name is used several times in the same paragraph, it is sufficient to use a proper link for the first occurence only.