Adding package documentation

[jat255]

Hi Nico,

I was leading a student through getting started with this library, and as far as I could find, there's no documentation anywhere online about the generated code, so it took a little bit to work out the various methods available (i.e. that /experiments corresponds to ExperimentApi.read_experiments(), etc.). It's not so hard once you work through it once (especially if you know Python) but I think having the python docs posted somewhere would be helpful when getting started and for more inexperienced programmers.

I was playing with building the library locally and noticed that it generates docs along with the library together with a README.md and docs/ folder that could be either hosted somewhere, or even just in this repo (and then Github can render the markdown files).

I made an example on this branch where I committed the /docs folder and added the links to the top-level README: https://github.com/jat255/elabapi-python/tree/doc_test

If nothing else, I would suggest that this table (https://github.com/jat255/elabapi-python/tree/doc_test#documentation-for-api-endpoints) be put somewhere and linked from the API documentation page in the main ELabFTW documentation.

What do you think?

[NicolasCARPi]

I'll look into the best option.

I wonder why this page: https://pypi.org/project/elabapi-python/ doesn't show the full README!

[jat255]

Yeah, weird! It's just the very first line of generated/README.md that gets shown... I don't think PyPI would work for the full docs though, since swagger puts them all in a docs/ subfolder requiring some link navigation.

[NicolasCARPi]

Now the html doc is also generated and hosted: https://doc.elabftw.net/api/elabapi-html/

But I strongly believe documentation by examples, the ones in the examples folder of this repository is better than this generated one. Still, it's good to have a reference for the available methods. As a bonus, you get code examples for many languages!

[NicolasCARPi]

Fun fact, it seems this generated html doc with swagger-codegen uses apidoc, a software I maintain. But it's an old version.

edit: so it doesn't use apidoc but they took the css from it and probably other parts. Interesting.

You can compare this: https://github.com/apidoc/apidoc/blob/0.16.0/template/css/style.css
and https://github.com/swagger-api/swagger-codegen/blob/751e59df060b1c3ecf54921e104f2086dfa9f820/modules/swagger-codegen/src/main/resources/htmlDocs2/styles.mustache

I wonder what it would take to use apidoc (the new version), instead of this unmaintained html ugly looking doc.

[jat255]

Thanks for putting those HTML docs up. I think that (together with the examples) will help a great deal. One tiny nit to pick... In the generated docs for Python, it shows the library name as swagger_client:

Is there some setting when generating the docs to change that to elabapi_python, so it matches the actual library name?

Fun fact, it seems this generated html doc with swagger-codegen uses apidoc, a software I maintain. But it's an old version.

Interesting! Always fun to find your old code out in the wild.

this unmaintained html ugly looking doc.

It reminds me a bit of those old javadoc pages: https://docs.oracle.com/javase/8/docs/api/ I assure you, I mean that as a compliment ;)

[NicolasCARPi]

The library name is normally correctly configured, it might be that because this html2 thing hasn't been touched in years, it is not picked up properly. I'd appreciate if you can try and find the time to look into it. If you find a parameter to add to this line, please let me know.

[jat255]

Turns out it's a pretty simple fix. Just a one line change to the config.json file changed in the linked PR

[NicolasCARPi]

doc has been updated on doc.elabftw.net!