I think i was thinking along the lines of actual API docs, and yes this would be auto generated from whatever doc generator we used. As for pydoc vs something like sphinx or even epydoc, sphinx offers a lot more flexibility and offers more capabilities. I dont think the cython stuff should be much of an issue, but I guess we'll find out. Agreed on the auto generated piece and whatnot.
On Tue, Sep 13, 2016 at 1:39 AM Mike Percy <[email protected]> wrote: > Hrm, looking again at the C++ wrapper code, I wonder if typical generated > API docs will even work with the mainstream python documentation tools. I > don't know the answer to that. > > Mike > > On Mon, Sep 12, 2016 at 8:09 PM, Mike Percy <[email protected]> wrote: > > > It seems like everybody in Python land uses Sphinx and ReStructuredText > > for documentation. However if this is just API docs then I don't know > what > > the benefit is to using a system like Sphinx over a core library like > > pydoc, since we already have Asciidoc for the primary Kudu documentation. > > > > As long as the Python API docs are auto-generated, easy to build, and > look > > nice, I would be okay with whatever seems to work well. > > > > Mike > > > > On Mon, Sep 12, 2016 at 7:08 PM, Todd Lipcon <[email protected]> wrote: > > > >> Hey Jordan, > >> > >> I guess the silence here means that no one has a strong opinion :) I > >> wonder > >> if the user@ list would have any more thoughts. > >> > >> I'm curious, though, what exactly this doc tool would do? If it's > "prose" > >> documentation, maybe we should stick to the adoc style that we use for > the > >> rest of the documentation, and just give the Python client its own page? > >> If > >> it's more strictly API docs, isn't that sort of built in using Python > doc > >> strings? (I'm not much of a Python programmer) > >> > >> -Todd > >> > >> On Sat, Sep 10, 2016 at 3:57 PM, Jordan Birdsell < > >> [email protected]> > >> wrote: > >> > >> > Anyone have any opinions/thoughts on Python API documentation? > Pyspark, > >> > pandas and others use Sphinx, so I'm thinking python devs would be > >> pretty > >> > comfortable with that format. > >> > > >> > Jordan > >> > > >> > >> > >> > >> -- > >> Todd Lipcon > >> Software Engineer, Cloudera > >> > > > > >
