On Sat, Mar 8, 2014 at 4:04 AM, Simon Feltman <[email protected]> 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..) [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 [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
