search

IAMconsortium / pyam

Analysis & visualization of energy & climate scenarios
https://pyam-iamc.readthedocs.io/
Apache License 2.0
227 stars 119 forks source link

Add known functions for aggregation methods to docs #644

Open danielhuppmann opened 2 years ago

danielhuppmann commented 2 years ago

The aggregation methods know several common functions so that a string can be passed instead of the actual function. This is implemented via https://github.com/IAMconsortium/pyam/blob/2dffec07ce86b2f3fb8133ac369fa3c172589064/pyam/utils.py#L50

Per a suggestion by @phackstock, it would be useful to show the known functions in the documentation such that this information can be cross-referenced from the docstrings of the aggregation methods (rather than simply repeating all known functions on each method that uses it).

phackstock commented 2 years ago

This should be a really quick addition, I'll take care of that. Is there a way to reference a variable (like KNOWN_FUNCS) in sphinx and get its value? This way it would update automatically in case there's new members in KNOWN_FUNCS. Maybe that's unnecessarily complicated though....

danielhuppmann commented 2 years ago

I think the best approach would be to have KNOWN_FUNCS as a recognized pyam module, then include it in the API docs, and cross-reference it from the methods-docstrings using intersphinx...

phackstock commented 2 years ago

Ah yes that would be the most elegant way, let's see if I can get sphinx to do that. Would KNOWN_FUNCS live in the API-reference?

danielhuppmann commented 2 years ago

Would KNOWN_FUNCS live in the API-reference?

Yes, maybe as new "Utility" page...?