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

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?

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).

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

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

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

Happy to merge now?

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}

Happy to merge now?

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