Expand documentation

[Quefumas]

I think the documentation is quite welcoming so far, but it lacks advanced features and instructions for developers.

In particular, as stated:

• How to extend Signal and Transform to implement new effects
• Crossfades and BiTransforms
• Curves and parametrization
• Custom Panning Schemes

My idea is to create a (long) 'Reference' document which lists all available features extensively, with example where needed, and perhaps even migrate some from README to make it lighter. And add the developer's stuff into TECHNICAL.MD.

[dlight]

I can't find the API documentation (listing all functions and modules) on pypi here https://pypi.org/project/gensound/ - am I looking at the wrong place?

For example, I only learned that Silence exists by looking at the wiki https://github.com/Quefumas/gensound/wiki/Signals-Guide#others

I think that explanatory documentation is a nice addition but an API listing is fundamental - and it can be generated automatically

[Quefumas]

Hello! Welcome and thanks for the comment.

I'm planning for the wiki to function as both a guide and a reference, but it's still a work in progress. I'm working on adding everything's that missing, but some classes have been left out since they are not supposed to be exposed to the user. For example, Sequence or Mix are only used internally, users have no reason to actually import them, and Silence is also somewhat redundant: it is recommended (see syntax reference) to instead use the syntax Signal | number to concatenate silence to a Signal, which I guess is the typical use case.

Also, many other classes have not been documented yet since they still need revising before their interface is ready to be made public (e.g. everything in curves.py). Perhaps in this case it would be better to document them, but add a warning for future versions?

Having a programmatically-generated API sounds great, though it would probably still need additional work on writing good docstrings. Is there any tool that you can recommend for generating such a reference?

[dlight]

Hi! Python comes with pydoc in the standard library, but you should probably use Sphinx. It's what Readthedocs uses (a site that hosts documentation for you, and that you should probably use and link from your readme and wiki)

Here's a guide to Python API documentation using Sphinx and here is Readthedocs's getting started guide.

~~Actually.. I will make a PR.~~

[Quefumas]

Thanks! Help and links are appreciated. I'll also start paying more attention to the docstrings on my end, and this will bring us one step closer towards having proper documentation :)

[dlight]

An update, I won't find time anytime soon to help with this.