search

seequent / properties

An organizational aid and wrapper for validation and tab completion of class properties/traits.
http://propertiespy.rtfd.org
MIT License
18 stars 9 forks source link

Allow option for napoleon docs rather than sphinx #251

Open fwkoch opened 6 years ago

fwkoch commented 6 years ago

The plain-text docstrings (i.e. accessed from ipython) are sometimes hard to read due to sphinx formatting. A small aspect of this was addressed in response to this issue here: https://github.com/seequent/properties/issues/8 but overall, docs are still sphinx through-and-through.

It would be great to enable easier to read docs with Napolen - https://sphinxcontrib-napoleon.readthedocs.io/en/latest/ - this could mean a couple of things. Either (1) have a check for __IPTYTHON__ (or maybe just a flag on the HasProperties class) that causes napolean docs to be built instead of sphinx, or (2) only build napoleon docs and use the sphinx extension to build docs from there.

bsmithyman commented 6 years ago

I am fond of Napoleon. I'd be happy to go that way, though we should get some consensus on it...

lheagy commented 5 years ago

I think the numpy-style docs are worth considering supporting (I would certainly appreciate this as we are moving the discretize docs over to numpy-styled). It is much easier to read as a developer and the formatting is a bit friendlier than the standard sphinx when pulled up in plain-text in a jupyter notebook

lheagy commented 5 years ago

Would it be a simple solution to even set a 

_properties_doc_type = "sphinx"   # "numpy" (etc)

on classes that inherit HasProperties?

fwkoch commented 5 years ago

@lheagy - Thanks for this, it would be good to get some different type of docs in, and I'm totally fine with numpy vs. napoleon. I also think your suggestion for class variable makes sense - we do this for a few other docs-related things.

I'll try to get a start on this in the next couple days, then maybe you can help flesh it out as you work on discritize docs.

lheagy commented 5 years ago

Thanks @fwkoch!! I would be happy to help flesh it out with the discretize docs :)