On 03/08/2014 06:15 PM, Christoph Reiter wrote: > 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..) 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 > [email protected] > https://mail.gnome.org/mailman/listinfo/desktop-devel-list _______________________________________________ desktop-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
