Improve api docs for qcodes.dataset #1660
Conversation
Codecov Report
@@ Coverage Diff @@
## master #1660 +/- ##
=======================================
Coverage 66.94% 66.94%
=======================================
Files 144 144
Lines 17804 17804
=======================================
Hits 11918 11918
Misses 5886 5886 |
lakhotiaharshit
changed the title
lakhotiaharshit
changed the title
There was a problem hiding this comment.
Hi guys. Looks good. A large amount of this is not user facing so it has lower priority.
What is userfaceing is defined by the sphinx configuration https://qcodes.github.io/Qcodes/api/index.html
qcodes/dataset/data_set.py
Outdated
| @@ -476,7 +476,7 @@ def run_timestamp(self, fmt: str = "%Y-%m-%d %H:%M:%S") -> Optional[str]: | |||
| started. If the run has not yet been started, this function returns | |||
| None. | |||
|
|
|||
| Consult with `time.strftime` for information about the format. | |||
| Consult with ``time.strftime`` for information about the format. | |||
There was a problem hiding this comment.
I suggest making this a clickable link. We have intersphinx loaded so you should be able to do
:func:`time.strftime`
but I have not tested it
There was a problem hiding this comment.
I think it should work. Changed accordingly.
qcodes/dataset/data_set.py
Outdated
| the data of this `DataSet`. The definition can be found at | ||
| `subscription.subscribers`. | ||
| the data of this :class:`.DataSet`. The definition can be found at | ||
| ``subscription.subscribers``. |
There was a problem hiding this comment.
Add something like in the qcodesrc.json config file
There was a problem hiding this comment.
Yes, this makes sense. Thanks.
| @@ -158,7 +158,7 @@ def _extract_single_dataset_into_db(dataset: DataSet, | |||
| target_exp_id: int) -> None: | |||
| """ | |||
| NB: This function should only be called from within | |||
| :meth:extract_runs_into_db | |||
| :py:meth:`extract_runs_into_db` | |||
There was a problem hiding this comment.
Are you sure the :py: is needed? The python env is the default and it is not used on any of the other constructs. (class func etc.)
There was a problem hiding this comment.
I do not think this is necessary, but I saw it has been used in the docstrings in e.g. data_set.py (see the docstring get_data_as_pandas_dataframe()). I will remove it, but also the existing ones should be handled in an other PR if this is unnecessary.
jenshnielsen
changed the title
Changes proposed in this pull request:
Currently finished parts:
qcodes.dataset
Workflow:
@GateBuilder and I will be working on parts of user-facing API docs each week. The finished parts will be mentioned on the top.
@WilliamHPNielsen
@jenshnielsen
@Dominik-Vogel
@astafan8