Initial Documentation

[philipstarkey]

This PR includes initial documentation for labscript-utils

The Sphinx conf.py file is a superset of the rpanderson/lyse and labscript-suite/labscript-suite conf.py files, with a bit extra that should allow it to be used across multiple projects with minimal adjustments.

This PR also includes an updated .gitignore (also a superset of labscript-suite/labscript-suite and labscript-suite/labscript)

I have also created a readthedocs.yaml file which provides configuration information to reathedocs that should override the advanced settings in the web interface (meaning these settings are now version controlled). The advantage of this format is that you can specify requirements as extras_requires within setup.cfg and tell readthedocs to install the package using that options (e.g. it runs pip install .[docs]).

Some very basic initial documentation is included (a couple of autodocs). It needs fleshing out more, but the purpose of this PR is to get the initial config into the repository so that documentation can become a collaborative effort.

If this looks good to people, I aim to rapidly duplicate it across other repositories that don't yet have docs or people working on docs (which I think is runmanager, runviewer, blacs, and labscript-devices).

[philipstarkey]

Built version can be seen here: https://philipstarkey-labscript-utils.readthedocs.io/en/latest/

[rpanderson]

Proposals:

1. Don't track the intermediate build results in docs/source/api_reference.
2. Rename this location (in docs/source/index.rst) to docs/source/api structure used in lyse.
3. In either case, if 1 is agreeable, add the folder to .gitignore.

I get a different result when running sphinx-apidoc locally. What command options did you use?

[philipstarkey]

I don't have any intermediate build results in the api_reference folder...unless you are referring to the .rst files? I made these by hand. Didn't realise that sphinx-apidoc could auto generate them....I'll need to look into how flexible that is. I was expecting that we might write some introductory text and or need to explicitly state the signatures of some methods (e.g. __init__ is not always included and decorated methods don't always show the correct signature).

[rpanderson]

I don't have any intermediate build results in the api_reference folder...unless you are referring to the .rst files? I made these by hand.

Oh, I see.

Didn't realise that sphinx-apidoc could auto generate them....I'll need to look into how flexible that is.

Yep, more experimentation is required before using sphinx-apidoc it seems, which shouldn't hold up this PR.

I was expecting that we might write some introductory text and or need to explicitly state the signatures of some methods (e.g. __init__ is not always included and decorated methods don't always show the correct signature).

Relevant to this:

• From the sphinx.ext.autodoc documentation:

It’s possible to override the signature for explicitly documented callable objects (functions, methods, classes) with the regular syntax that will override the signature gained from introspection:

.. autoclass:: Noodle(type)

  .. automethod:: eat(persona)

This is useful if the signature from the method is hidden by a decorator.

• autodecorator directive:

If you document decorated functions or methods, keep in mind that autodoc retrieves its docstrings by importing the module and inspecting the __doc__ attribute of the given function or method. That means that if a decorator replaces the decorated function with another, it must copy the original __doc__ to the new function.

• Using functools.wraps() to create well-behaved decorating functions (stack overflow):
  • Preserve default arguments of wrapped/decorated Python function in Sphinx documentation
  • Python Sphinx autodoc and decorated members

[rpanderson]

It might be prudent to merge/add changes to conf.py from labscript-suite/labscript-suite#43.

[philipstarkey]

I have incorporated changes from labscript-suite/labscript-suite#43.

Happy to merge now?

[rpanderson]

I have incorporated changes from labscript-suite/labscript-suite#43.

I think there's one more:

# Customize the html_theme
html_theme_options = {'navigation_depth': 3}

[rpanderson]

Happy to merge now?

Fine by me if you don't mind bd0d527 changes (feel free to force push if you don't).