Setup sybil

[joaander]

Description

Add Sybil documentation example tests to methods.py and thermostats.py.

Motivation and context

Users wish to copy and paste example code from the documentation. Sybil tests those snippets to ensure that they work now and in the future.

These tests currently run both in serial and MPI. That may be helpful. However future examples we write might only work in MPI and/or only in serial (or only on the GPU or only on the CPU). pytest.skip works within these blocks, however Sybil generates each code block as a separate test. Users will see the pytest.skip logic in tests that need to be skipped in some configurations. If we were to add pytest.skip in a hidden code block, it would only skip that block and not the next. The skip: next if syntax may be a solution to this, I just found it and have not yet tried it: https://sybil.readthedocs.io/en/latest/rest.html#skipping-examples

In my testing, Sybil only parses .. code-block:: sphinx directives and not literals Example::. This format makes the raw docstring more verbose (for users of help()), but the HTML output is as expected:

.. rubric:: Example:

.. code-block:: python

    example code

Note that the package-level example code the users sees in module-md-methods.html comes from md/methods/__init__.py, but the example code that Sybil runs in the namespace of all the MD methods is in md/methods/methods.py. This is because __init__.py imports from methods.py to create a different canonical namespace for the methods while Sybil runs all examples in the context of a document (a single .py file).

This pull request adds documentation for previously undocumented methods in hoomd.util. Should these be documented, or should they remain hidden?

• dict_map
• dict_fold
• dict_flatten
• dict_filter
• GPUNotAvailableError

How has this been tested?

• I have tested this locally and ensured that all code blocks are indeed being tested.
• I have examined the generated html docs and ensured that the formatting is consistent and readable.

Change log

Added:

* Tested example code snippets in select modules.
* ``hoomd.util.make_example_simulation`` - create an example Simulation object.

Checklist:

• I have reviewed the Contributor Guidelines.
• I agree with the terms of the HOOMD-blue Contributor Agreement.
• My name is on the list of contributors (sphinx-doc/credits.rst) in the pull request source branch.

[joaander]

@b-butler @DomFijan Take a look at the changes and rendered Sphinx docs and let me know what you think.

[DomFijan]

I went through the documentation. This is looks really good and I think it will be very useful, especially for newish users.

I have some suggestions, they might be too much in some cases and if you feel like it is too much feel free to discard proposed changes.

[joaander]

Updated with device.py examples ensuring that the skip next syntax allows us to write GPU and MPI specific examples that are tested when possible and skipped when not. This is as far as I'm taking this specific pull request. Future pull requests will add examples in batches to other parts of the code.

[b-butler]

This is a great start and definitely going to aid users. I left some small comment to address.

[b-butler]

LGTM!