Documentation Requests!

[sneakers-the-rat]

Track minor docs improvements not worth starting their own issue over, comment to make a docs request!

General

• [ ] use of ~/.autopilot file to bootstrap location of autopilot user dir
• [ ] use of pigpio args and pigpio mask in prefs, explain default mask & relationship to sound card...
• [ ] document logging, log levels
• [x] networking configuration, how to connect pilot to terminal
• [x] quickstart overview -- 'do something cool in autopilot in 10 minutes'
• [ ] gui wizards/elements, incl. 'reload protocols' and 'batch reassign'
• [ ] Use references to methods themselves rather than calling methods to assign triggers - https://github.com/wehr-lab/autopilot/discussions/119#discussion-3505581

Examples

• [x] using hardware objects! cameras, etc. outside of context of class
• [x] simple example task, blinking a light, etc. as both a notebook and in the user guide

Wiki

• [ ] @cxrodgers frequency response measurements: https://github.com/auto-pi-lot/autopilot/discussions/182#discussion-4264149

[mikewehr]

Super confusing whether "Board-numbered GPIO pin" refers to GPIO number (GPIO0-27) or pin number (1-40), there's got to be a way to spell this out so it's crystal clear in the docs

[sneakers-the-rat]

"board-numbering" is the canonical way of referring to, well, the board number (the position of the pin on the board).

this is currently documented here: https://docs.auto-pi-lot.com/en/dev/autopilot.hardware.html

and in the pin_bcm attribute here: https://docs.auto-pi-lot.com/en/dev/autopilot.hardware.gpio.html#autopilot.hardware.gpio.GPIO

I've added a link to a stackexchange post on the matter every time the phrase is mentioned in docstrings, and have made an additional note at the top of the gpio page here: https://github.com/wehr-lab/autopilot/commit/ebc39ba6efb3f0a47d29bcfdbf780c3feeb902a6

which should be reflected here: https://docs.auto-pi-lot.com/en/dev/autopilot.hardware.gpio.html

[mikewehr]

basic debugging tutorial with tips & tricks and example workflows

[sneakers-the-rat]

Document behavior of triggers re: advancing stage when not desired.

https://github.com/wehr-lab/autopilot/issues/148#issuecomment-1033255537

[sneakers-the-rat]

all the various config files and the structure of the user directory should get its own page since it's a central concept that a lot of people (justifiably) miss, eg. what is a pilot_db.json is that documented anywhere?

re: https://github.com/wehr-lab/autopilot/issues/148#issuecomment-1033255537

[sneakers-the-rat]

add security notice -- this software is intended to be used on a local area network not exposed to the public internet and has not been hardened in any way, use at your own risk!

[mikewehr]

installation instructions (here: https://docs.auto-pi-lot.com/en/latest/guide/installation.html) do not clarify the best practices for having a separate git folder with the autopilot code, and a user autopilot folder with prefs, protocols, data, etc. Jonny has commented with surprise more than once at my peculiar installation hierarchy in which there is an autopilot code directory nested inside my autopilot user directory (rather than in a segregated git directory). I have now installed autopilot from scratch a half dozen times, following the instructions on the installation page to the letter, and I end up with my peculiar nested file hierarchy every time. I agree that this weird nested structure is problematic even though it actually works ok. I think the instructions need to include a couple extra steps recommending an appropriate sequence of mkdir ~/autopilot, mkdir ~/git, cd ~/git, git clone, pip3 install -e ., etc

[mikewehr]

terminal needs an icon

[sneakers-the-rat]

installation instructions (here: https://docs.auto-pi-lot.com/en/latest/guide/installation.html) do not clarify the best practices for having a separate git folder with the autopilot code, and a user autopilot folder with prefs, protocols, data, etc. Jonny has commented with surprise more than once at my peculiar installation hierarchy in which there is an autopilot code directory nested inside my autopilot user directory (rather than in a segregated git directory). I have now installed autopilot from scratch a half dozen times, following the instructions on the installation page to the letter, and I end up with my peculiar nested file hierarchy every time. I agree that this weird nested structure is problematic even though it actually works ok. I think the instructions need to include a couple extra steps recommending an appropriate sequence of mkdir ~/autopilot, mkdir ~/git, cd ~/git, git clone, pip3 install -e ., etc

definitely need a whole page on user directory structure a la

all the various config files and the structure of the user directory should get its own page since it's a central concept that a lot of people (justifiably) miss, eg. what is a pilot_db.json is that documented anywhere?

re: #148 (comment)

and clarification of role of repo code and plugins now that the intended design pattern is to use the versioned library with plugins rather than local edits to fork.

[sneakers-the-rat]

use and configuration of the systemd daemon

[sneakers-the-rat]

use this to document the structure of the wiki ... on the wiki

https://github.com/wehr-lab/autopilot/issues/127#issuecomment-906794608

[sneakers-the-rat]

Add to wiki https://github.com/auto-pi-lot/autopilot/discussions/182#discussion-4264149