Thank you Robert Lupton, and others, for your comments. I've incorporated all changes that can be made in this ticket.
I've also created follow-on tickets for future work that is needed to implement many of the suggestions in the PR.
- Regarding -
output, -rerun, PIPE_INPUT_ROOT, someone from the Science Pipelines team can go ahead and RFC deprecations. I've created DM-11685 to implement doc changes that fall out from that RFC, and to generally research and document opinionated strategies on using Butler repositories.
- DM-11673 to improve the "creating a task" topic, which is currently the same as in Doxygen.
- DM-11674 to improve the "creating a command-line task" topic, which is currently the same as in Doxygen.
- DM-11694 to improve the overview topic, which is currently nearly the same in Doxygen.
- DM-11687 to research and add --show history documentation, which I missed in this initial work.
- DM-11675 to port and cross-link the debug framework documentation from Doxygen.
DM-11558 to create pex_config documentation, which will especially help the re-targeting docs (the re-targeting docs in this ticket are ports from Doxygen but certainly need work to clarify).
- DM-11671 to create Butler/daf_persistence documentation