Sphinx Build is throwing many warnings

[devendragovil]

What?

Sphinx Build is throwing a multitude of warnings. Example:

Why?

The warnings right now might turn acute later on. Need to see what is going on.

[mhajij]

@maneelusf @devendragovil what is the udpate on this issue?

[ninamiolane]

@maneelusf @devendragovil what is the update on this?

[devendragovil]

A major update on this issue:

Update

There are over 250 warnings that are being thrown during the docs build process mostly because the function/method docstrings haven't been written to be compliant with numpydoc. I have been trying to resolve these, but in a lot of cases I think the original method creator can help resolve the issues better.

Further Issues

Due to the docstring parsing warnings, the docs generated by sphinx are not complete or correct.
An example: If the docstring section in a method begins with Return instead of Returns, sphinx doesn't parse it any longer as the Returns section and skips generating the returns section for the final doc.

Solution

I think two steps are needed:

1. We need to manually resolve the warnings that are already being thrown (around 250 of them for this package)
2. We need to make necessary changes in the pre-commit and CI/CD workflows to make sure that docs are generated correctly from now onwards.

[devendragovil]

I am working on amending the pre-commit file and the CI/CD workflow to incorporate docstring checks.

[ffl096]

the CI/CD workflow to incorporate docstring checks

We have validation since #297, but I think the checks do not fail for warnings

[devendragovil]

@ffl096 If I understand it correctly, the check has been placed as the part of the sphinx build process by specifying numpydoc validation in the conf.py file read by Sphinx.

I think we may want to add the check in the CI/CD workflow explicitly.

[ffl096]

Why? It is part of the CI/CD workflow this way as well. Not sure why we should spread doc-related validations across different places instead of everything in sphinx.

[devendragovil]

I would argue that this isn't a doc related validation, but more so related to codebase i.e. the docstrings format.

However, the more important goal should be to fail a CI/CD workflow so as to incentivize correct docstring formatting something akin to compliance with PEP8.