New QC not showing up in Documentation about act

[rcjackson]

We might have to go into the .rst files and make sure that they are referring to the docstrings in the code.

…

________________________________ From: Adam Theisen <[email protected]> Sent: Thursday, July 18, 2019 11:01:32 AM To: ANL-DIGR/ACT Cc: Jackson, Robert; Mention Subject: [ANL-DIGR/ACT] New QC not showing up in Documentation (#86) I don't see any of the new QC features documented in the ACT docs. https://anl-digr.github.io/ACT/ @rcjackson<https://github.com/rcjackson> @zssherman<https://github.com/zssherman> it looks like @kenkehoe<https://github.com/kenkehoe> has things documented fairly well. Is there something we need to do to get it to show up? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#86>, or mute the thread<https://github.com/notifications/unsubscribe-auth/AFIQA5EKDAH4SCUBSXVJH2TQACHVZANCNFSM4IE5GK5Q>.

[zssherman]

Might need to add qcfilter to the init file docs. I don't see it referenced. Some functions use single quotes instead of doubles, but I don't think that would effect it at all.

[kenkehoe]

qcfilter imports qctests. Could that be part of the issue?

[AdamTheisen]

@zssherman where exactly is that init file you are referring to?

[zssherman]

@AdamTheisen For example, in the retrievals where calculate_stability_indices :

act.retrievals (act.retrievals)

.. currentmodule:: act.retrievals
This module contains various retrievals for ARM datsets.
.. autosummary::
:toctree: generated/
calculate_stability_indicies

from .stability_indices import calculate_stability_indicies

So maybe under :toctree: generated/ qcfilter functions need to be added. Similar to what seen in the retrieval init

[AdamTheisen]

Documentation is showing up now.

[kenkehoe]

I'm not sure this is resolved. The classes are listed in the documentation but my doc strings are not showing up nor all the method names. I am happy to look into solving this but I don't understand enough to know where to start. I tried running the doc generation locally and ran into issues. Can we reopen this to remind me to look into again?

[AdamTheisen]

@kenkehoe Check out ACT/docs/source/API/plotting.rst. This may give you a good lead into what to do for the QC part.

When you make changes there, you can run "make html" in the ACT/docs folder. Once that completes you can check out the html page by opening ACT/docs/build/html/index.html

[AdamTheisen]

Note, I also think you need to add documentation to the QCTests class.

[kenkehoe]

I have documentation to the QCTests class but it is not showing up. Does anyone have suggestions on how to fix this? Looks like the function documentation is showing up but none of my method documentation is being processed.

[AdamTheisen]

@kenkehoe The only thing I can see at the moment is that the QCTests class is not initialized. See the Display class in plotting/plot.py. It has documentation on the class and an initializer

def __init__(self, obj, subplot_shape=(1,), ds_name=None,
             subplot_kw=None, **kwargs): 

[AdamTheisen]

I am also seeing warnings when I try and build the documentation for the qc

/anaconda3/lib/python3.7/site-packages/numpydoc/docscrape.py:424: UserWarning: Unknown section Example: in the docstring of <function parse_bit at 0x1c1ce85048> in /Users/atheisen/Code/ACT/act/qc/qcfilter.py.
warn(msg)

/anaconda3/lib/python3.7/site-packages/numpydoc/docscrape.py:424: UserWarning: Unknown section Example in the docstring of <function set_bit at 0x1c1ce19ea0> in /Users/atheisen/Code/ACT/act/qc/qcfilter.py.
warn(msg)

/anaconda3/lib/python3.7/site-packages/numpydoc/docscrape.py:424: UserWarning: Unknown section Example: in the docstring of <function unset_bit at 0x1c1ce7c2f0> in /Users/atheisen/Code/ACT/act/qc/qcfilter.py.
warn(msg)

/anaconda3/lib/python3.7/site-packages/numpydoc/docscrape.py:424: UserWarning: Unknown section Example in the docstring of <function rolling_window at 0x1c1ce7c158> in /Users/atheisen/Code/ACT/act/qc/qctests.py.

[kenkehoe]

OK thanks. I've made a few changes and things are not fixed but better. I'll keep looking into it.

[AdamTheisen]

@kenkehoe how is this looking now?

[kenkehoe]

I needed to list each method to get the QC to show up but it is there now. We can close this and I'll look into why I need to list the methods another day.