Simon and others, With respect to PyGObject docs, I hope you are all aware of http://lazka.github.io/pgi-docs/ and http://learngtk.org/
The first link is especially fantastic. FWIW I also purchased www.pygobject.org a while ago and am wondering what to do with it. My current plan is to consolidate all PyGObject / GI docs there (maybe in a month or two when I am less busy). John On Sat, Mar 8, 2014 at 4:04 AM, Simon Feltman <[email protected]> wrote: > On Fri, Mar 7, 2014 at 3:22 AM, Christoph Reiter > <[email protected]> wrote: > > On Thu, Mar 6, 2014 at 11:37 AM, Ekaterina Gerasimova > > <[email protected]> wrote: > >> On 6 March 2014 10:07, Christoph Reiter <[email protected]> > 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 > _______________________________________________ > 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
