Repository navigation
Documentation content updates #204
Description
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_datadict vsTEST_SEQUENCEcomment
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 newfixate._switchingjig classes -
fixate.core.ui -
fixate.core.checks -
TestClassandTestList(but making sure we remove the obsolete/unused and internal attributes that aren't part of the public API -
fixate.driversFocus 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.
Activity
clint-lawrence commentedon Jul 24, 2024
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 commentedon Jul 31, 2024
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.linkcodewould let us link to Github, which would be cool if we could quickly fix something in the webeditorsphinx.ext.viewcoderenders 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 commentedon Jul 31, 2024
This VSCode extension will be useful for popping in a docstring template while coding
clint-lawrence commentedon Jul 31, 2024
Or you could just use PyCharm which does that out of the box ;)
josh-marshall-amp commentedon Aug 2, 2024
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. 😉