IBM/simulai

Add NumPy style Docstrings to SimulAI packages

Closed this issue · 7 comments

TarikKaanKoc commented

Add NumPy style Docstrings to SimulAI packages

Tasks

  • Review the current documentation for the Optimization package, Regression package, Regression.pytorch sub-package, Residuals package, Sampling package, Control utilities package, and ROM package in the SimulAI package.
    Write clear, concise, and comprehensive docstrings for all functions, classes, and methods in the packages using the NumPy style of documentation.
  • Ensure that the docstrings provide enough information for users to understand how to use the package, what the function or class does and what inputs and outputs are
  • Add examples in the docstrings to make it easier for users to understand how to use the package
  • Test the packages after adding the docstrings to ensure that they are complete and accurate
  • Add docstrings to simulai/modules
  • Ensure that the docstrings are consistent in style and format throughout the package
  • Make all the packages easily accessible to users by providing links to the packages in the main documentation of SimulAI.

#60

Joao-L-S-Almeida commented

I agree Numpy-style is a better choice for docstrings.

  • 👍1
Joao-L-S-Almeida commented

I'm considering to use pyment for automatically converting the docstrings from reST to numpydoc. Here is a patch file showing the modification made by pyment in the module simulai/rom/_rom.py. What do you think @TarikKaanKoc ?
_rom.py.txt

Joao-L-S-Almeida commented

Another example. Using the command line:

 pyment -w -p False simulai/regression/_elm.py -o numpydoc

It produces the output I sent as attachment. It is possible to pass the entire directory simulai as input and convert it in a single time.
_elm.py.txt

Joao-L-S-Almeida commented

It can cover the reST->numpydoc conversion and we can focus on filling the missing docstrings.

TarikKaanKoc commented

We need to find a way to fix the copy tag warnings generated by Sphinx in our codebase.

For example, we get a warning like this.

/Users/koc/simulai/simulai/io.py:docstring of simulai.io.ScalerReshaper.prepare_input_data:4: WARNING:  source/_modules/simulai.io:parameters: duplicate label

We are looking for a solution to fix these errors and get the docstrings to our desired format without copy tag errors etc. There are more than 100 warnings because of this.

While the pyment library is great at converting document sequences from reST to numpydoc format, it doesn't fix Sphinx-generated copy tag warnings.

for example:

Before using pyment:

After using pyment:

I am looking for a solution that would help me to completely get rid of these warnings and have clean docstrings in the desired format. As seen above, only the docstring style is changing. But what I'm looking for is to get rid of these warnings completely.

TarikKaanKoc commented

I tried the pyment library for the io.py module and it broke many document threads. (These docstrings were already in the style of numpy-docstring.) I'll edit the io.py module again later, and I suggest you don't use the pyment library. (I fixed many bugs....) @Joao-L-S-Almeida

TarikKaanKoc commented

With this commit reverted it to Version V0.99.13 io.py module.
a2a06c3