Makes sense On Tue, Sep 13, 2016 at 10:45 PM Mike Percy <[email protected]> wrote:
> 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 > > > >> > > > > > > > > > > > > > >
