Documentation #282
Description
Our current documentation is mostly the readme, and few tutorial notebooks.
I woud suggest creating a sphinx documentation hosted on readthedocs as it is common for many python projects.
See example emiproc: https://emiproc.readthedocs.io/en/master/
We want to improve this to also document:
General Pages
- get started with fluxy (installation + which tutorial to run)
- How fluxy works (principles of data loading and then plotting)
Gallery
A plot gallery that shows all the available plots we have and links them to the function used to generate them.
It can also show how one function can plot different things with different options.
Plots could be generated at build time, so that when we do the PR reviews, we can also see how the new code look like.
This means also that we should store more data on the repository. We need to discuss if we want to externalize the data to a proper data repository.
API
This can usually be generated using autodocs that will read docsting of all functions and automatically generate the api documentation.
- I/O functions
- Utility functions
- Plot functions
We can also subsplit the plot functions based on which type of plot they produce (maps, timeseries, stats, ...)
We can do the same with utility functions that are dedicated only to one of the plot type.
We also need to uniformize the signature and docstring of the functions.
- Have the type of arguments only in the function signature and not in the docstring.
Tutorials
- data formatting for fluxy
- existing notebooks
Developper documentation
- How to impelement a new plot function
- Disussing new features with the devs + PR and CI and formatting processes
- Implementing tests
Aknowledgements and projects
- Contributors. Might need a contributors.md file in the main repo that we can link to the documentation. This would allow for detailed description of who contributed to what exactly, which roles and also institutions and funding.
- Hall of fame (publications that use fluxy)
- others ?