Proposal for new organization of docs

[probberechts]

Taking some inspiration from #205, I've come up with a new structure for the docs. This PR adds some placeholders for the pages that would have to be created, but no concrete documentation yet. I've put a build here: https://people.cs.kuleuven.be/~pieter.robberechts/kloppy/

The main ideas are:

1. A "user guide" provides a 15-min hands-on introduction for new users and continues with a discussion and clarification of key topics. This part of the documentation is written in markdown and provides links to the reference and how-to guides.
2. A set of "how-to guides" contains notebooks illustrating how to achieve a specific task. One example could be how to load data from S3.
3. A "providers" section contains notebooks illustrating how to load data for each provider and highlights some of the most important pitfalls, limitations and provider-specific features. This should enable users to quickly get started with the data they have.
4. A "reference" is mostly auto-generated from the docstrings. It contains the API specification of all objects (Team, Player, Orientation, ...) and functions in the kloppy code base. In addition, it provides a detailed description of the domain model used for event stream data. For each event type, a table is included that shows which providers support it.

As discussed yesterday, I would proceed as follows:

• Agree (or disagree) on this raw structure for the docs
• Start a new branch dev/docs-v2
• Create separate pull requests for each tutorial, how-to guide or part of the reference and merge them in dev/docs-v2

[UnravelSports]

Thanks for sharing this, and again my apologies for never committing anything more to #205.

Some remarks from looking at the general structure and having a quick look at the Polars docs.

I'm personally not a big fan of having some of the important aspects in the menu on the left under user-guide (getting started, datasets and coordinate system) and then having some of the other important concepts in the menu at the top (providers and reference).

I would use a similar structure to Polars to make it a lot easier to navigate. In the top menu only:

• User-guide
• Development (same as "Other", just rename). This is anything related to development (contributing, sponsors, license etc).
• Releases

Under User-guide:

• Getting started
• Installation
• How to guides
• Providers
• Concepts (renamed "Reference")

Then as sub categories under concepts:

• Datasets
• Metadata (is not a dataset, so should be separate?)
• Domain concepts
• Merge "coordinates" and "transformations" into 1 page (assuming the transformations are the coordinate transformations)
• State
• Configurations

Not relevant for high level structure, but I think every provider should be split by tracking and event providers), both tracking and event providers should have an overview page with information on coordinate system (and supported events). And then every provider page itself should have an example on how to use that specific provider and anything that might be relevant there as well as a simple example of how to load data.

I personally think this structure should make it a lot easier to navigate, because we simply put everything under User-guide. All information should be easily accessible this way, and we can easily append Concepts with new things, and append new providers to it's subsection.

Looking forward to hearing what you and others think about this.

[probberechts]

Thanks for the extensive feedback.

• I agree with renaming "Other" to "Development".

• Adding "Releases" in the main navigation is a good idea.

• I would not merge the "Reference" in the "User guide". Both should be written for a different target audience. The "User guide" is for people who are new to kloppy and want to understand the basics. The "Reference" is written for someone like myself who quickly wants to look up some detailed info such as the attributes of a Player or how a StatsBomb pass is implemented in kloppy, without having to dive into the code itself. They should contain the same information, but at a different level of detail. The Polars' docs (any basically any other popular package) keeps these separate too.

• I do not have a very strong opinion about whether "How-to guides" should be part of the "User guide" or a separate section. But I definitely think that they should be the last part of the "User guide" since these are intended for people that know at least the basics of kloppy. I like how the Django docs describe them:

  How-to guides are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how Django works.

• I wasn't entirely sure where to put the "Providers". My intention was to keep the user guide generic but I see that it makes sense to include it in the user guide too. However, I think you have to explain the concept of a dataset and describe the different data types before you discuss provider-specific things. If you would include the providers in the user guide, this results a deeply nested structure, which I do not really like.

  • Datasets
    • Event data
      • StatsBomb
      • ...
    • Tracking data
      • Metrica
      • ...
    • Code data

[UnravelSports]

• I agree with your point on Reference being for more advanced users. Maybe my reason for including it in the User-guide was because the current docs aren't extensive enough and that makes it necessary to even have this info available to figure some basic stuff out. So, I'm fine with keeping that separate.
• I'm fine with this, as long as Providers is close to the top with some basic examples. I suggested the Providers to be it's own page because it feels to me like anyone that finds Kloppy for the first time simply wants to know "Okay I have X provider, how do I load their data and does kloppy even support this". Which in my opinion is one of the main basic questions we should address in the user-guide without over complicating it.
• To add to my previous point, I think it's entirely fine to show all the supported providers and how to load the data and only then explain what a dataset is, because there is no point in knowing what a dataset is if you only later find out that your data provider is not supported.
• Also agree with trying to avoid nested structures but not if it's the most obvious structure. The structure you describe at the bottom of your post is still the most logical way to describe what Kloppy has to offer imo.

[probberechts]

I've made some progress on the "Reference". You can see the updated build here.

• Added a hierarchy with most domain concepts
• Added automated documentation for the data loaders for each data provider
• Added documentation for the event data model. It now automatically generates tables with the implementation of each event type for each data provider from a yaml file. I've now only filled it in for the Pass event for StatsBomb.

[UnravelSports]

This is awesome @probberechts. I know we've discussed this before, but do you need any further help on this? It feels a bit tricky to coordinate on, and I'm not at all an expert on generating these docs etc.