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 standard? #97

Open lsetiawan opened 7 years ago

lsetiawan commented 7 years ago

I notice that docstrings of functions and classes are a bit confusing. And issue #94 points out that there isn't really a built in documentation for the objects returned by the api calls.

After looking at various popular python libraries out there, it seems like a lot of them follows the Numpy/Scipy docstring documentation style.

@ocefpaf will set up ODM2PythonAPI documentation to follow a similar approach to Folium. Looking at the code it seems like this library also follows the numpy/scipy documentation style (@ocefpaf, please correct me if I'm wrong).

Given those circumstances, I propose that we use the numpy/scipy standard when documenting the code. What do you all think? @emiliom @ocefpaf @aufdenkampe @horsburgh @sreeder ?

emiliom commented 7 years ago

:+1: thanks @lsetiawan and @ocefpaf.

FYI (to others), Filipe, Don and I discussed this yesterday. The system we'll implement will be tied into Travis CI so that docs are autoupdated, and will also be versioned with each tagged release. Don is taking the first steps to set up this system. Stay tuned!

ocefpaf commented 7 years ago

Looking at the code it seems like this library also follows the numpy/scipy documentation style (@ocefpaf, please correct me if I'm wrong).

I try to but I may not be consistent there. Lately I'm using a more terse and simple style, see https://github.com/ocefpaf/erddapy/blob/master/erddapy/erddapy.py

However, both are fine, I don't really have a preference here.