Documentation

[guenp]

I think we're now at a stage that documentation is needed. While writing instrument drivers I found that digging through the code is becoming too time-intensive. Especially since @alexcjohnson is leaving Copenhagen in a few months and is planning to invite more developers to join the project soon, it is becoming more urgent.
I propose to use Sphinx: http://www.sphinx-doc.org
This is a tool that automatically generates documentation based on reStructuredText and docstrings. This is a convenient way for developers to keep the documentation updated while adding new features.
Additionally, we need flowcharts and other images to clarify how the measurement process is built in relation to data storage and so on.

[alexcjohnson]

Good idea @guenp - I haven't used Sphinx or any other such tools before, so lets have a bit of discussion on this: who else has opinions on what would make the docs most useful and how to get there?

And since @guenp mentioned it but I don't think others on this list have heard - yes, in August I will be leaving Copenhagen. I will still be working on qcodes at least 1 day a week for at least the next year, and we are in the process now of bringing on another full-time developer here.

[guenp]

@alexcjohnson perhaps it's an idea to make it a requirement for future pull requests that all added code is documented before merging?

[AdriaanRol]

@guenp , @alexcjohnson , I think a tool like sphinx is the way to go, especially considering we are actually doing quite well on docstrings. The thing I miss most however are the diagrams and general descriptions of concepts like parameters, instrument server and loop. I think that the FAQ is a good start for that, especially the explanation @alexcjohnson added in one of the recent PR's

EDIT: I think a style guide would also be a good addition

[MerlinSmiles]

I think a faq cannot replace a real CookBook as many other packages have, and I dont think we can continue adding example notebooks forever.

A CookBook should address the things more generally.

• How to use the station
• How to use an instrument
• How to use parameters
• How to organize an experiment
• How to run a loop
• How to plot live data
• How to save the data
• How to read the data back, and plot it in the first place
• How to use logging and user-logging (for experiment logs)
• How to save metadata and logs

In my opinion this should not only be docstrings, if we encourage a standard way on how an experiment is run it will be much easier for users to peer-help other users, help with the data and things like that.

Edit:
Here are some great examples:
Pandas
Logging
Scipy

[giulioungaretti]

Just casually dropping my 2cents on this:

• python ❤️ sphinx
• sphinx ❤️ python
• follow pep8 as closely as possible (https://www.python.org/dev/peps/pep-0257/)
• in the python community the unwritten rule is "just use sphinx"
• FAQ are great, but often not enough at the beginning of a big open source project

The nice thing about sphinx is that it is not only limited to docstrings, but one can expand it as much as one wants.
That includes all things: images, videos, free form text. Also notebooks can be integrated into sphinx.

@AdriaanRol python is already very opinionated, but a style guide is always nice.
Other languages / projects especially new and successful ones all require / enforce a style guide.
I would also go so far out as saying that code that does not follow the guide should be blindly rejected :D

@guenp I would say that + tested, this can be also automated using CI tools, so that a pull request gets "reviewed" automagically.

Lastly git commits, and pull requests messages are also one of the best form of documentation.

@MerlinSmiles note that all of these indeed great examples are build with sphinx :D

[MerlinSmiles]

@giulioungaretti ❤️
Will you start like tomorrow?

I really don't like git discussions and pull requests as documentation. Often discussions are long and boring, its hard to find, and sometimes outdated.

[cdickel]

It's mostly about the code, right? No function should be longer than 100 lines. Breaking up the code like that makes it naturally more clear. And standards in function names are essential. If you write a doc example for a mock driver and every other one is based on the example not too much documentation should be needed.

[giulioungaretti]

Maybe also worth mentioning

https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

[giulioungaretti]

@cdickel no function should do more than one thing, possibly being as stateless as possible. If that takes 1k lines that is fine albeit unlikely. A 3 liner that modifies state all over, logs things and returns is like cancer and must be avoided.

Any update on this? I'd also remove the long-term issue. As this should be done before any new things are added. Else contributing will get harder and harder, and documentation will be a catch up game instead of an organic process.