search

ODM2 / ODM2PythonAPI

A set of Python functions that provides data read/write access to an ODM2 database by leveraging SQLAlchemy.
http://odm2.github.io/ODM2PythonAPI/
BSD 3-Clause "New" or "Revised" License
4 stars 13 forks source link

Documentation for the python objects returned by the API #94

Closed smrgeoinfo closed 7 years ago

smrgeoinfo commented 7 years ago

Is there any documentation for the structure/data type of the objects returned by the API calls?

horsburgh commented 7 years ago

@smrgeoinfo - to my knowledge, not yet. @sreeder has put together a list of the currently available functions in the API that I need to update in this repo, but we don't have the objects documented yet. However, they follow pretty closely the structure of the ODM2 schema. @sreeder should be able to answer any specific questions you may have.

emiliom commented 7 years ago

pinging @smrgeoinfo @horsburgh @aufdenkampe

Following up on a discussion at the BiGCZ call this week, @lsetiawan, @ocefpaf and I (but specially Don and Filipe) got busy to implement Sphinx-based auto-generation of API and other package documentation for odm2api. We have a first crude draft version in place! http://odm2.github.io/ODM2PythonAPI/

Lots more to do, but this is already a vast improvement over what was previously available for API documentation :smile_cat:

Don has populated 2 or 3 method "doc strings" using the proper conventions ("Google style") that are auto-parsed by the Sphinx system. Here's getAffiliations in action -- one of the methods whose doc strings we finessed.

We'll populate all other modules early next week. From that point on, the main task will be refactoring or adding doc strings, and that will be a slow process. But still, we'll have a full-fledged API documentation that's fully under our control and is driven by the code.

Have fun with it. We'll discuss it at next week's BiGCZ call.

horsburgh commented 7 years ago

Thanks for making progress on this @emiliom and @lsetiawan. It will be great to have a look at what you have done this week and have a quick walk through. We are at a bit of disadvantage until @sreeder is back from maternity leave, but after that I think she could help take any documentation she's got and help flesh things out.

emiliom commented 7 years ago

It will be great to have a look at what you have done this week and have a quick walk through.

Yup, on Tuesday at the BiGCZ call.

We are at a bit of disadvantage until @sreeder is back from maternity leave,

No worries at all. We've laid out the workflow, and the Sphinx system will already expose the API structure and parameters in a much more easily accessible way (where before you had to navigate the code and/or look up static, external documents). Don and I will expose manually crafted function/method/class text ("docstrings") that's already there, and add some here and there.

emiliom commented 7 years ago

Closing this issue. As mentioned above, the latest documentation (specially for API, objects, etc) is at http://odm2.github.io/ODM2PythonAPI/