Documentation improvement ideas

[UnravelSports]

It seems that a lot of basic information is missing in the docs, and it consists primarily of examples on how to get started.

I've had a brief discussion with @koenvo offline about this and he figured it would be good to open a single issue to discuss potential additions to the docs. Before listing everything I'd like to point towards a different projects' docs, namely Spektral, from which we might be able to draw some inspiration.

I will attempt to update this list as I get more into the project and see myself digging through the code to find answers to things that are not in the docs.

• [X] Available arguments for each loading function
• [X] A clear overview of supported providers (tracking and event separately). Currently the Getting-started segment just lists all supported providers alphabetically.
• [X] An overview of what coordinates parameters are available and what pitch dimensions they use.
• [ ] Explanation on Serializers and Transformers
• [ ] An explanation of why almost all providers return empty values for speed and distance variables. Perhaps an update to the Providers page to include Tracking Data providers could accomplish this. Perhaps the point above on pitch dimensions can also be included here.
• [ ] Info about functions/methods we can call on objects such as dataset (ie. dataset.metadata)
• [ ] Info on outputs (ie. anon pandas columns)
• [ ] How to contribute to docs. (use docs-requirements.txt and mkdocs serve etc.)

Edit: I'm updating this checklist even though I've only implemented these changes locally for now. To show what I still need help with or need to implement

[razor3598]

Perhaps you could document what each column represents when converting the data to pandas df. There are a few columns when retrieving the skillcorner data with the word "'anon" which had me confused the first time I was using it

[MarcSkovMadsen]

Check out https://diataxis.fr/. It’s a great way to learn how to structure documentation. We’ve been using this for HoloViz Panel since v1.0.

Lots of PyData frameworks are now using this.

[UnravelSports]

Anyone that can help me find the pitch dimensions / ranges for all providers assuming a 68x105m pitch? I know a bunch from the top of my head, but that's not good enough.

There is a reason I want to update these docs (I can't find this stuff in the codebase for the life of me). So, if anyone has any insides on any of the points raised above feel free to drop them in a post here.

It's also fine to link to files where I can find this info if it already exists somewhere in an accessible place.

[koenvo]

Great work everyone! Thanks for sharing the resource @MarcSkovMadsen !

The info we have related to pitch dimensions is defined here: https://github.com/PySport/kloppy/blob/master/kloppy/domain/models/common.py#L452

[JanVanHaaren]

The mplsoccer documentation website visualizes the coordinate systems for some data providers: https://mplsoccer.readthedocs.io/en/latest/gallery/pitch_setup/plot_compare_pitches.html#pitch-comparison.