Hey Jordan, Sounds ok to me. Let us know what you find. BTW, if we want to rely on Python-stack stuff like Sphinx as part of the full docs build that gets generated for each Kudu release (so we can put the API docs on the web site) let's encapsulate it with a script that creates a local virtualenv with a requirements.txt file or something like that. Then we can avoid people having to figure out how to create a Python build environment just to update the site and having people using different versions of the docs packages for different releases. This is basically what we do with the Ruby-stack stuff for jekyll and asciidoc (using gem and bundler).
Mike On Tue, Sep 13, 2016 at 1:17 PM, Jordan Birdsell <[email protected]> wrote: > 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 > > >> > > > > > > > > >
