Open lsetiawan opened 7 years ago
@emiliom Do you think that it's necessary to add Examples to docstring for every function under ReadODM2?
@emiliom one topic we did not discussed is how to use the example
section of the docstrings, specially for the classes methods.
For example, when adding an example for one can:
class
docstring only;(1) is a good idea when the methods docstrings a self-explanatory and examples would be redundant while (2) could be used to complement (1). (3) can be tedious to write and read and lead to big docs when the classes have many methods.
I usually go for (3) only for small projects and use a mix of (1) and (2) + notebooks with full case examples.
@emiliom Do you think that it's necessary to add Examples to docstring for every function under ReadODM2?
I think they're helpful and we should build towards having them. But one step at a time. First step is documenting the parameters; some of that documentation is already there, but the first step is really to confirm that text is correct (fix it if it isn't), and fix the format to match the Sphinx Google style structure.
@emiliom one topic we did not discussed is how to use the example section of the docstrings, specially for the classes methods.
@ocefpaf, can you add short examples to your comment, to illustrate each of the 3 options you presented? Otherwise I find it hard to visualize.
Sorry to add stuff here that's not about the docstring convention per se. Ignore this. It's a placeholder (for me, or us) for reference, to summarize from our recent emails (or maybe I should create a markdown document somewhere else?):
_NOTES
subdirectory is the old doc
directory, preserved just in case. Most of the stuff in there is very old and probably won't be needed)http://odm2.github.io/ODM2PythonAPI/docs-{{ version }}
@ocefpaf, can you add short examples to your comment, to illustrate each of the 3 options you presented? Otherwise I find it hard to visualize.
Sure.
class
docstring only;class MyClass(object):
"""In the class docstring we can describe what is the purpose of of MyClass.
Examples:
>>> my_class = MyClass()
>>> my_class.my_cool_method()
results
>>> my_class.my_other_cool_method()
more_results
def my_cool_method():
"""Terse docstring without the example b/c they are in the overarching class."""
def my_other_cool_method():
"""Again only docstrings, no examples.
Note that we don't need examples for all methods when using (1)
to avoid cluttering the class docstring.
"""
class MyClass(object):
"""In the class docstring we can describe what is the purpose of of MyClass."""
def my_cool_method():
"""docstring + example.
The class instantiation is implicit! We omitted the `my_class = MyClass()`!!
Examples:
>>> my_class.my_cool_method()
results
"""
def my_other_cool_method():
"""Note that this strategy makes for very readable docs.
However, it won't allow to run doctests b/c the code examples are fragments.
Examples:
>>> my_class.my_other_cool_method()
more_results
"""
class MyClass(object):
"""In the class docstring we can describe what is the purpose of of MyClass.
def my_cool_method():
"""Full example with all the steps to get to the result.
Examples:
>>> my_class = MyClass()
>>> my_class.my_cool_method()
results
"""
def my_other_cool_method():
"""There will be some redundancy, but the example will be 100% "copy-n-paste-able."
Examples:
>>> my_class = MyClass()
>>> my_class.my_other_cool_method()
more_results
"""
Documentation can be versioned, such that the versions are tied to the release versions. This is not in place yet, I think.
It is in place. We just won't build the old versions. As soon as a new release is tagged we branch that version and we'll get the docs in a page like, http://odm2.github.io/ODM2PythonAPI/docs-{{ version }}
I am going to continue on models doc discussion here from https://github.com/ODM2/ODM2PythonAPI/pull/111#discussion_r143981602.
This is what the samplingfeatures doc look like:
@emiliom Do we want docs for each of the Sampling Features Attributes or just a listing?
Thanks. @lsetiawan and I have discussed this. We'll keep those additions for now, and make a decision later about whether to add docstrings to class properties (and methods?).
This Issue follows up https://github.com/ODM2/ODM2PythonAPI/pull/105#discussion_r141936709.
We need a set of conventions that we should follow when writing docstring within the functions and classes:
#
rather than triple quotes, because all triple quotes, regardless of where they're found will be interpreted as doctrings by Sphinx.Currently (10/1) one of the best docstrings available as an example is in ReadODM2.getAffiliations
cc @emiliom
Please add more as necessary.