Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation is out of date #19

Open
philipstarkey opened this issue Jun 16, 2017 · 2 comments
Open

Documentation is out of date #19

philipstarkey opened this issue Jun 16, 2017 · 2 comments
Labels
bug Something isn't working minor

Comments

@philipstarkey
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member Author

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!

@philipstarkey philipstarkey added minor bug Something isn't working labels Apr 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working minor
Projects
None yet
Development

No branches or pull requests

1 participant