Cookbook/ tutorial

[galenlynch]

It would be great if we had a more prominent tutorial in the docs. I remember when I first started using DSP.jl, I was at a loss for how to use it for simple filtering tasks. The most helpful section on how to filter is a little bit buried. It seems that other people were also confused by the current documentation, so some clarification may be helpful.

[ssfrr]

I tend to think that it's useful to organize docs into a few standard sections:

• User Guide: Guides the user through high-level concepts of the library, introduces how it is used, and the relationships between the types and methods the package provides.
• API Reference: List of all public types and functions, generally auto-generated from their docstrings.
• Examples: Not too many examples, but enough to get a flavor and exercise the library. Definitely some filtering examples would be useful here.
• Developer Docs: Documentation on the internals of the library. This is probably similar to the "User Guide" in structure, but documents implementation details for contributors

I guess even if folks like this division there's still the question of whether this lives above or below the submodule hierarchy that we have currently.

I also don't necessarily want to derail this focused issue with a big refactoring of all the docs, so definitely a smaller change that makes filtering more accessible would be great.

[galenlynch]

Separating the docs into a User Guide and API Reference would probably go a long way towards making DSP.jl more accessible. Minimal examples could be included in the User Guide.

The fact that DSP.jl is made of submodules isn't obvious to its users, nor do they really need to know about it. If anywhere, I would think that should go in the Developer Docs.

[ErikBuer]

I am a big fan of doctests in the function documentation. That way the user doesn't have to look elsewhere to get a function up and running.

Especially when the user can have silly problems with dimensions or types. These can take some time to sort out.

[ErikBuer]

I have played around a bit and tried to create figures from jldoctest, which seems not to be possible. However it is quite easy to make documentation that generates figures end such, using documented and @example code snippets.

https://documenter.juliadocs.org/stable/man/syntax/