Docstring errors

[mturilli]

Compiling apidoc.rst returns these errors:

radical/pilot/task_description.py:docstring of radical.pilot.task_description.TaskDescription:346: ERROR: Unexpected indentation.
radical/pilot/utils/component.py:docstring of radical.pilot.utils.component.Component:46: ERROR: Unexpected indentation.
radical/pilot/utils/component.py:docstring of radical.pilot.utils.component.Component.advance:11: ERROR: Unexpected indentation.
radical/pilot/utils/prof_utils.py:docstring of radical.pilot.utils.prof_utils.get_consumed_resources:4: WARNING: Definiti on list ends without a blank line; unexpected unindent.
radical/pilot/utils/prof_utils.py:docstring of radical.pilot.utils.prof_utils.get_consumed_resources:16: WARNING: Block quote ends without a blank line; unexpected unindent.
radical/pilot/utils/prof_utils.py:docstring of radical.pilot.utils.prof_utils.get_consumed_resources:17: WARNING: Definition list ends without a blank line; unexpected unindent.
radical/pilot/utils/prof_utils.py:docstring of radical.pilot.utils.prof_utils.get_consumed_resources:18: WARNING: Definition list ends without a blank line; unexpected unindent.
radical/pilot/utils/prof_utils.py:docstring of radical.pilot.utils.prof_utils.get_consumed_resources:20: WARNING: Definition list ends without a blank line; unexpected unindent.
radical/pilot/utils/prof_utils.py:docstring of radical.pilot.utils.prof_utils.get_session_description:3: ERROR: Unexpected indentation.
radical/pilot/utils/session.py:docstring of radical.pilot.utils.session.fetch_filetype:6: ERROR: Unexpected indentation.
radical/pilot/utils/session.py:docstring of radical.pilot.utils.session:1: WARNING: Inline emphasis start-string withoutend-string.
radical/pilot/utils/session.py:docstring of radical.pilot.utils.session.fetch_filetype:1: WARNING: Inline emphasis start-string without end-string.
radical/pilot/utils/session.py:docstring of radical.pilot.utils.session.fetch_filetype:1: WARNING: Inline emphasis start-string without end-string.
radical/pilot/utils/misc.py:docstring of radical.pilot.utils.misc.get_resource_configs:11: ERROR: Unexpected indentation.

[eirrgang]

As noted in #2447, it would be helpful to explicitly decide whether to embrace Numpy or Google style docstrings (@andre-merzky has a preference towards using more vertical space in order to require less line width, which would imply Numpy style). Then it would be easy to reference the appropriate style guide for examples of formatting that is valid and produces the desired typesetting.

It would also be clearer how best to resolve such errors. Also, narrowing the sphinxcontrib-napoleon configuration (in docs/source/conf.py) to a specific style may improve parsing overall.

If a preferred docstring style can be chosen for the project, I can offer the PR for #2447 with the sphinx config update and the necessary docstring reformatting.

[mturilli]

Thanks @eirrgang , very much appreciated. Let's go with google then.

[andre-merzky]

I fixed most of the warnings above (on the nb3 branch) - but I don't really understand the remaining two :-/ @mturilli , can you have a look please?

[mturilli]

@eirrgang any suggestion? Something maybe related to the PR you are putting together?

[eirrgang]

@eirrgang any suggestion? Something maybe related to the PR you are putting together?

Sorry for the slow response. I'm back at my keyboard full-time again (now Central TZ). I'll take a look in the next few hours.

[eirrgang]

I fixed most of the warnings above (on the nb3 branch) - but I don't really understand the remaining two :-/ @mturilli , can you have a look please?

I targeted nb_section3 at #2910. Is that the branch you meant, @andre-merzky ?

[andre-merzky]

I targeted nb_section3 at #2910. Is that the branch you meant, @andre-merzky ?

Yes, indeed.

[eirrgang]

I think the current errors are all due to .rst document syntax and doctree structure. (I don't see any docstrings producing errors.) I'll open a new issue to describe in more detail. If I am mistaken, please attach examples. I think all of the examples provided by Matteo were addressed.

[mturilli]

Thanks for all your work @eirrgang . I think we can now close this as all the errors were addressed before merging nb_section3 into devel yesterday. See your other referenced ticket for more details.