Restructure the documentation

[pavithraes]

Is your feature request related to a problem? Please describe.

Docs navigation can be improved, especially keeping new users in mind. Currently, there is a topical-organization of docs, it'll be nicer to have a distinction between API references, concepts, tutorials, etc.

Describe the solution you'd like

Restructure the docs with some principles from Diátaxis - a framework for structuring technical documentation

Tentative/rough outline:

• Home
  • What is CSP?
  • Key features
  • Get Started: Link to tutorials, concepts, how-tos, and examples (i.e., provide a learning path)
  • Community: Developer guide, roadmap
• Get Started (Tutorials)
  • ref: Create a "getting started" tutorial #65
• Concepts
  • Most of https://github.com/Point72/csp/wiki/0.-Introduction (Specifics TBD) + csp.Struct (conceptually)
  • https://github.com/Point72/csp/wiki/3.-Statistics-Nodes-(csp.stats)#getting-started
  • Caching (TBD)
• How-to
  • Use Stats Nodes - ex: 20, 21
  • Use Adapters
  • Introduce cycles in the graph (csp.feedback) - ex.13
  • Create Dynamic graphs - ex.15
  • Write Adapters
  • Profile the code (TBD)
• References
  • API References
    • https://github.com/Point72/csp/wiki/1.-Generic-Nodes-(csp.baselib)
    • https://github.com/Point72/csp/wiki/2.-Math-Nodes-(csp.math)
    • https://github.com/Point72/csp/wiki/3.-Statistics-Nodes-(csp.stats)#api-reference-1
    • https://github.com/Point72/csp/wiki/4.-Random-Time-Series-Generation-(csp.random)
    • https://github.com/Point72/csp/wiki/6.-Dynamic-Graphs (csp.DynamicBasket, csp.Dynamic)
    • csp.struct
    • csp.profiler
  • Changelog
  • Glossary
• Examples
  • List all examples with descriptions and link to files
  • Add cross-links to other wiki pages/sections
• Developer guide
  • Contributing: Issues/PRs, docs, examples, and more!
  • Development setup
  • Release process, xref: Document release process #64
  • Roadmap

Also, note that we can create a custom Sidebar. So we can have atomic documentation pages (each page covers one main topic) and have as many pages as we need without worrying about overloading the default wiki TOC.

[ptomecek]

Under the Concepts section, I would recommend spending some time going through https://github.com/Point72/csp/wiki/1.-Generic-Nodes-(csp.baselib) before covering the stats nodes. csp is not strictly-speaking a stats library, and there is a lot of educational benefit to understanding the way that the basic building blocks in csp.baselib are built from the package functionality. Not only will this knowledge teach people how to build new building blocks, but it will also let them know which ones are already there and tested (and often with higher-performance c++ implementations).

In the API section, we'll need better documentation of the Adapters we currently have (parquet, db, Kafka, etc) as this will be key for users who want to use csp on real data.

Some of the examples might merit their own separate documentation pages/tutorials rather than the existing format (python scripts with comments and print statements - even Jupyter notebooks would be better than the current format). For example, some of the examples are for how csp integrates with pandas (either as an extension type, or tools to help create time series of ticking pandas data frames), but there is not much wording to explain the motivation, use cases, etc.