💄 📝 🚸 Usage pointers

[stelmo]

All functions should have an examples section in their docstrings showcasing at least some of the functionality, e.g. using optional arguments etc. For example, flux_variability_analysis is super powerful but I need to go to the actual docs online to figure out how to use it for even basic fva, there should be an example to make this unnecessary.

Functions that need examples:

• [x] flux_balance_analysis: add more links to modifications
• [x] xxx_vec and xxx_dict need to point to xxx - check that this is the case
• [x] flux_variability_analysis: add examples + mod links
• [x] parsimonious_flux_balance_analysis: examples are waaay out of date

[exaexa]

Random notes:

• we can't technically maintainably link all the mods and variants (not even a "good" sample at any one time); I hope we'll be able to make an autogenerated overvew page or something
• don't overdo the examples, it should always fit the screen. :D

[stelmo]

Yeah fit on screen is important, what I meant is that we say e.g. also look at these functions as possible modifications... but I can see how if we add random ones we might forget to update the docs. Hmm, maybe the important ones? E.g. change_constraint etc.

[exaexa]

well, is there a way to reference a group of functions from the documentation?

cc @laurentheirendt any idea ^

[laurentheirendt]

I only know of referencing sections marked with # as these are tags in the documentation. Maybe we can generate them for certain groups of functions?