Python Docs (was Re: Coordination for developer documentations)

[Simon Feltman <s feltman gmail com>]

On Fri, Mar 7, 2014 at 3:22 AM, Christoph Reiter
<reiter christoph gmail com> wrote:
> On Thu, Mar 6, 2014 at 11:37 AM, Ekaterina Gerasimova
> <kittykat3756 gmail com> wrote:
> > On 6 March 2014 10:07, Christoph Reiter <reiter christoph gmail com> wrote:
> > > Since it wasn't mentioned so far; outside of gnome.org, on the Python
> > > side of things, there exists the GTK+ 3 tutorial [0] maintained by
> > > Sebastian Pölsterl (accepts pull requests, but isn't actively working
> > > on it [1]) and the gi api reference [2], which I actively maintain.
> >
> > I have been using these recently and am very keen to see them on
> > developer.gnome.org. There is a developer experience hackfest[3]
> > coming up at the end of April which would be a perfect time to make
> > that happen, is there any chance that you could make it?
>
> Sorry, can't make it, but I'm willing to help in that regard. I can
> write up a project status/roadmap if that helps.

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

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.

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

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

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

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

-Simon

[1] http://sphinx-doc.org/man/sphinx-apidoc.html
[2] http://docs.python.org/
[3] http://docs.python.org/3/library/doctest.html