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

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
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
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.


desktop-devel-list mailing list
desktop-devel-list gnome org

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]