Reorganise API docs

[jenshnielsen]

This is by no means complete but is a start towards a more sensible organization of the api docs

[astafan8]

some minor comments.

[jenshnielsen]

I think this is ready now.

• There is a .rst file per python file (module) that we document
• These are kept in a folder structure that matches the code
• We only document the relevant modules. (Apart from utils etc where we document everything)
• The individual python files are documented with a automodule clause. This means that everything is
  included for a module. We could get better results by going more fine grained and chose the specific classes to document but I think this is the best trade off between maintainability and granularity)

[codecov]

Codecov Report

Merging #1478 into master will decrease coverage by 0.02%.
The diff coverage is 50%.

@@            Coverage Diff            @@
##           master   #1478      +/-   ##
=========================================
- Coverage   73.82%   73.8%   -0.03%     
=========================================
  Files          92      92              
  Lines       10438   10444       +6     
=========================================
+ Hits         7706    7708       +2     
- Misses       2732    2736       +4

[astafan8]

I'm waiting for the CI to finish, and then i'll look through the built docs....

[astafan8]

so what are the steps for the developer once he adds a new python module that deserves being included in the docs? perhaps, those can be added to "contributing" or wherever?

[jenshnielsen]

Yes that would be great once that is rewritten.

[astafan8]

can a rudimentary description be a part of this PR?

[jenshnielsen]

Yes, but the problem is not the description. The problem is that it would land in the middle of another document where the rest no longer applies

[astafan8]

i'd be ok with that because without the description i'd have to bother you when i make "my next PR" :) Full-blown proper fixing of that document can be done later.

[jenshnielsen]

Ok I guess it should go here https://qcodes.github.io/Qcodes/community/contributing.html#development ?

[astafan8]

good! thanks!

[astafan8]

Is it possible and is it preferred to go from

qcodes.dataset.database_extract_runs.extract_runs_into_db(source_db_path: str, target_db_path: str, *run_ids, upgrade_source_db: bool = False, upgrade_target_db: bool = False) → None

to

extract_runs_into_db(source_db_path: str, target_db_path: str, *run_ids, upgrade_source_db: bool = False, upgrade_target_db: bool = False) → None

when generating docs?

[jenshnielsen]

Is it possible and is it preferred to go from

qcodes.dataset.database_extract_runs.extract_runs_into_db(source_db_path: str, target_db_path: str, *run_ids, upgrade_source_db: bool = False, upgrade_target_db: bool = False) → None

to

extract_runs_into_db(source_db_path: str, target_db_path: str, *run_ids, upgrade_source_db: bool = False, upgrade_target_db: bool = False) → None

when generating docs?

I would mostly be against that. Explicit is better than implicit and all that

[astafan8]

I'm just going to throw them here since i've found them, but it's up to the author to decide what to do with them.

Have problems with formatting:

• class qcodes.utils.validators.Validator
• qcodes.utils.plotting.Number has a docstring which does not correspond to it
• qcodes.utils.plotting.auto_range_iqr - interesting "return type" entry, i don't know how it should be actually, maybe it's ok and just confusing for me
• qcodes.utils.helpers.NumpyJSONEncoder - list of supported conversions in "default" method is badly formatted. Also, the docstring includes the base class docstring which i think is irrelevant here.
• station.remove_component has an extra bullet point for "raises" section
• field_vector, set_component method: extra bullet point in the "parameters" section
• qcodes.logger.log_analysis - some of the "returns" sections are not formatted correctly (they look like quotes instead)
• qcodes.logger.instrument_logger.InstrumentLoggerAdapter docstring can be improved to have code/examples/plain text distinguished
• qcodes.instrument.group_parameter.GroupParameter - it's a bit bad than the doc is polluted with the methods of the parent class
• qcodes.instrument.parameter module has a nice module-level doc but cool stull like ParameterWithSetpoints is not mentioned there while ArrayParameter is
• qcodes.instrument.channel.AutoLoadableChannelList - the bullet-point list in the docstring is not renderred as such

[jenshnielsen]

@astafan8 I was going to suggest that we should split up all the modules and each do a pr per module to bring the docs up to spec for that module.

• That would be fix the issues that you have seen
• Add missing module level docstrings
• Add other missing docstrings

I really just wanted this to be about a sane overall layout

[astafan8]

we should split up all the modules and each do a pr per module to bring the docs up to spec for that module

Perfect! Let's do that soon.

[jenshnielsen]

I will do the contributing guild updates in a new pr now