search

jepegit / cellpy

extract and tweak data from electrochemical tests of cells
MIT License
81 stars 27 forks source link

API is not documented #290

Closed ma-sadeghi closed 3 months ago

ma-sadeghi commented 4 months ago

I might have missed it, but I couldn't find the API reference in your documentation. The CLI though was documented. If cellpy is mostly a CLI tool, then I think it should be okay. But, if it's also to be used inside scripts, you really need an API reference section in your documentation. Sphinx can automatically generate nicely formatted API reference from your function/class docstrings if they adhere to a some popular formats (like NumPy style, or Google style, and maybe more)

jepegit commented 4 months ago

The API reference is only accessible on the bottom of the first page (README) in readthedocs ("Indices and tables"). This makes it unnecessarily difficult to find. This should be improved, e.g. by making it accessible in the sidebar.

ma-sadeghi commented 4 months ago

Oh right! Sorry my bad, I missed it. (I agree that it's a good idea to put it up front in the home page/sidebar)

Correct me if I'm wrong: It seems that the API reference as it stands only documents your exceptions and warnings. I wasn't able to find function/class/module references.

jepegit commented 4 months ago

Yes, the API documentation was broken - ReadTheDocs have updated how the format of the recipe should be. And the one cellpy had was not fully correct (I think). But think I have figured out how to fix it.

jepegit commented 4 months ago

Further work on this is done in #273