Code documentation

[felixbur]

The code is almost entierly undocumented. https://realpython.com/documenting-python-code/

[bagustris]

@felixbur, I am interested in taking this opportunity. The easiest one is to convert writings in your blog related to nkululeko into Sphinx, isn't it?

[felixbur]

ok, cool. Sometimes the blog postings are outdated, I would go through the code and add comments to the classes and main functions what they do, and what are the arguments and return values, so that the code could be used outside nkululeko

[bagustris]

@felixbur I will start with Sphinx and Read The Docs. Here is the appearance (still no writing): https://nkululeko.readthedocs.io/

If you have time during ICASSP 2023, is it possible to make a small hackathon for nkululeko, partially on Documentation part? I will come to that conference wholly and will attend the Show and Tell session of Nkululeko.

[felixbur]

oh, hi, cool, we can definetly meet! Problem is, that the nkululeko slot they assigned me is right when i have to present my poster. so i asked them to shift me to Show & tell demo: session 4 got no reaction yet, though...

[bagustris]

I just realized that you already activated GitHub pages for this repo. Actually, we can use that for the documentation but I think using readthedocs is better as you pointed out above in realpython link. So I would like to propose the following:

1. Use rtd for documentation ([Nkululeko])(https://nkululeko.readthedocs.io/) --> Work in progress.
2. Use Github pages for News, More Tutorials/examples (limited tutorial, e.g., 5 examples, can bu put in Docs), and News (copy-paste from your blog?)

[felixbur]

I would suggest to use Google conventions for docstrings.

def from_db(y: float) -> float:
    """Value converted from decibel scale.

    Args:
        y: amplitude value in decibels

    Returns:
        amplitude value

    Examples:
        >>> from_db(0)
        1.0
        >>> from_db(-3)
        0.7079457843841379

    """
    return np.power(10, y / 20)

[bagustris]

Reference to that proposal: https://google.github.io/styleguide/pyguide.html