Documentation content updates

[josh-marshall-amp]

After merging #194, the next step is the content of the documentation. This issue raised to collect the updates we'll need to make.

Any discussion of the docs philosophy and howto from the docs readme can go here too.

And a quick link to the actual docs: Fixate overall and the auto-generated API reference

• reorganise hierarchy for the docs (see the readme on doc quadrants)
• (not strictly docs) reorganise the fixate source to make clear what's public vs private
• fix up all the docstrings that don't render correctly
• add missing docstrings on important modules
• fix, then add a stack more docstrings, at least enough to cover the basics and provide an example
• test_data dict vs TEST_SEQUENCE comment

Docs to move into this repo (either as .rst or as docstrings in code, prefer the latter):

• test script software structure (Confluence): put in the top level just after the tutorial
• Using Fixate Drivers in Python: should be in module+class+function docstrings
• Jig driver migration

Public API to use in scripts (that should have autodocs generated):

• Everything exported in __init__ (in particular, the new fixate._switching jig classes
• fixate.core.ui
• fixate.core.checks
• TestClass and TestList (but making sure we remove the obsolete/unused and internal attributes that aren't part of the public API
• fixate.drivers Focus should be on the base class for each instruments type, which as much as possible, aims to be consistent across the given device type.

I'm thinking that we don't document fixate.core.jig_mapping since we more or less want to deprecate that.

[clint-lawrence]

There's a discussion to be had about if we keep this repo public or not. If we keep it public, then we need be mindful of what is documented where. For example test script structure is not specific to fixate. Just how to setup our scripts internally and so should remain internal.

I'm also going to edit the description to add in a list of the most import modules to document.

[josh-marshall-amp]

While reviewing a docs PR, occurred to me I really like when docs link to the source... that way it's easy to look at where something is missing or went wrong, particularly in this early stage of getting the docs fixed up.

sphinx.ext.linkcode would let us link to Github, which would be cool if we could quickly fix something in the webeditor

sphinx.ext.viewcode renders the code itself as an extra set of HTML pages. Good but not as useful as linking to Github.

This issue shows the process of linking to github... but right to the line number.

[josh-marshall-amp]

This VSCode extension will be useful for popping in a docstring template while coding

[clint-lawrence]

This VSCode extension will be useful for popping in a docstring template while coding

Or you could just use PyCharm which does that out of the box ;)

[josh-marshall-amp]

Or you could just use PyCharm which does that out of the box ;)

If we're gonna do IDE battles 🔥 here... then if you want to rewrite my VSCode launch setup, which fires up the simulator with debugger attached to the Python side of the comms code in one pane and GDB attached to the executable's equivalent in C in another... I'm listening. 😉