Re: Python Docs (was Re: Coordination for developer documentations)

[Stefan Sauer <ensonic hora-obscura de>]

On 03/08/2014 06:15 PM, Christoph Reiter wrote:
> On Sat, Mar 8, 2014 at 4:04 AM, Simon Feltman <s feltman gmail com> wrote:
> > That would be helpful. I think it would be nice to integrate your work
> > (or abstracted parts of it) with pygobject itself.
> >
> > An idea that has been cooking in the back of my mind (and to a very
> > small degree has been realized with pygobject's function signature
> > docs) is to have pygobject handle documentation by filling out Python
> > doc strings lazily when accessed. This would of course require
> > developers to have either gir files installed or preferably devhelp
> > could ship sgml (or mallard?) files which are accessible to tools
> > outside of devhelp (or devhelp provides some sort of API if it doesn't
> > already).
> Sounds good to me.
>
> > I think the benefits to an approach like this could be fairly significant:
> >
> > * GI function argument interpretation for Python docs would be as
> > close as possible to pygobject by having the argument translation code
> > living in pygobject itself. Preferably we could expose pygobjects
> > internal argument caches which already have all the translation logic
> > applied and re-use this for the docstrings. This has the benefit of
> > lowering maintenance cost by ensuring the documentation for function
> > arguments is in lockstep with how pygobject actually works.
> >
> > * Overrides and Python specific API extensions would automatically be
> > included in the docs.
> (This is mainly the reason why I think Python introspection + Sphinx is
> better in the long run than something like g-ir-doctool.. for the Python
> bindings at least)
>
> This should be possible with the current Sphinx based approach but still
> needs some work (it only shows the correct override signature atm). I need
> to handle the following cases somehow:
>
> * In case the functionality of the overidden function differs from the
> original one it should be possible to replace the gir documentation
> all together.
>
> * In case the override just adds some additional arguments or default
> values it should be possible to include the gir docs in the override
> docstring (something like "%INCLUDE%" which gets replaced)
>
> * In case the override uses "*args, *kwargs" because of backwards
> compatibility or because argument processing is delegated to some helper
> function it should be possible to define a Python signature which replaces
> the real one as seen by Sphinx.
>
> Once I have this working with pgi, I will try to move the override changes
> needed to PyGObject.
>
> > * Better developer workflow. By using Python doc strings, we
> > automatically integrate with all of the awesome Python developer tools
> > and things like doc tips in IDE's should just work.
> Is there any IDE/editor which supports some sort of auto completion for
> PyGObject right now (using the gi.repository import hook)?
>
> > * Tools like Sphinx [1] could be used to generate html docs by
> > pointing it at the "gi" Python package. In a similar vein, I realize
> > Christoph's pgidocgen uses gir files translated to reStructuredText
> > which is then run through Sphinx (please correct me if I'm wrong
> > here).
> In a limited form "pointing it at gi" should work then. It doesn't handle
> import hooks afaik, so you would still have to generate rst files with all
> autodoc references in them. Maybe provide it as a helper in PyGObject
> similar to sphinx-apidoc.
>
> This is basically what pgi-docgen does + adding docstrings. In addition
> I've tried to hide the existence of overrides while still exposing the user
> facing interfaces.
>
> > * By using Sphinx, we also get direct references back to the Python
> > docs [2] for native Python constructs (as is realized with Christoph's
> > docs, although I'm not sure if it is Sphinx or pgidocgen doing that).
> This is possible through the Sphinx intersphinx extension [0]. Sphinx
> creates a "object.inv" [1] file which can be used by other sphinx based
> projects to resolve references. This is, as you've said, used to link to
> the official python documentation + the pycairo docs (see Gtk.Widget.draw()
> [2] for example). It's also used in Sebastian's GTK+3 tutorial to link to
> the API reference itself.
>
> > * We could integrate Sebastian's Python GTK+ tutorials which are
> > written in reST by moving them into pygobject. Since GNOME projects
> > are mirrored on github, I think they could still be pushed to
> > readthedocs if we want that.
> >
> > * Testing of example code. Another possibility is to have Python
> > specific versions of the developer doc examples living under a
> > sub-folder of pygobject (preferably in Python's "doctest" format
> > [3]). These could be pulled into the docs given the examples have some
> > type of unique tag in the xml source. They could then be run as part
> > of the pygobject test suite to ensure they are working Python.
> >
> > * Sphinx also seems to supports devhelp output (among other formats)
> > which is interesting in that we might be able to achieve a similar
> > look and feel with the rest of the GNOME developer docs.
> I've tried the devhelp export and it seemed to work quite well for the all
> in one API docs. But I'm not sure how linking between different Sphinx
> builds would work with devhelp. (but I have no idea how devhelp does it
> with other sources either..)
devhelp is basically the index.sgml (ignore the sgml extension, it is
not) + prerendered html. devhelp does not do anything with the link in
the html doc, except trying to follow them when one is clicked.

Stefan
> [0] http://sphinx-doc.org/latest/ext/intersphinx.html
> [1] http://lazka.github.io/pgi-docs/objects.inv
> [2] http://lazka.github.io/pgi-docs/api/Gtk_3.0/classes/Widget.html#Gtk.Widget.draw
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> https://mail.gnome.org/mailman/listinfo/desktop-devel-list