Documentation is out of date

[philipstarkey]

Original report (archived issue) by Shaun Johnstone (Bitbucket: shjohnst, GitHub: shjohnst).

---

The latest documentation is from 2014! The instructions on how to add new devices pre-date the move to labscript_devices, and the using BLACS file shows screenshots of gtk.

Should the instructions for adding new devices to BLACS be merged with the instructions for adding new devices to labscript, and moved into the labscript_devices repository?

Most of the information in the "Using BLACS" document is still relevant, it could just do with new screenshots and a review of the text.

[philipstarkey]

Original comment by Chris Billington (Bitbucket: cbillington, GitHub: chrisjbillington).

---

It might be a good idea if documentation were in some source format like sphinx, such that people could make pull requests that include diffable/mergable changes to documentation. Requesting that someone update the docs to include the details of their change probably ought to be part of our pull request routine. I have a few small projects that are documented with sphinx on readthedocs, and the docs there get automatically updated whenever I push the code. It's pretty slick.

[philipstarkey]

Original comment by Philip Starkey (Bitbucket: pstarkey, GitHub: philipstarkey).

---

So I did begin labscript documentation with sphinx (it's even in the repository!) and we started setting up stuff on readthedocs. Using readthedocs is a bit complicated, but worth it for getting auto-generated documentation working (because we're always going to forget to regenerate documentation before committing).

The complication with readthedocs include getting our suite installable in their build environment (I think this can be done by adding a setup.py file to each of our repos, without having to put it on PyPi) and creating modules to mock 3rd party libraries that can't be installed in their build environment (like PyQt). We thus need to start with labscript_utils, since all of the suite depends on this.

And, while the issue is currently assigned to me, it's such a big task that everyone will have to pitch in when we actually start to do this!