Re: Python Docs (was Re: Coordination for developer documentations)
On Mon, Mar 10, 2014 at 7:48 AM, Christoph Reiter reiter.christ...@gmail.com wrote: On Mon, Mar 10, 2014 at 4:27 AM, Simon Feltman s.felt...@gmail.com wrote: In terms of overrides having additional side effects beyond the intended GI API, I really hope we can deprecate those scenarios or additional arguments that invoke new/alternate behavior (like Gtk.MessageBox's buttons argument). It doesn't seem like there are very many of these cases and I'm not sure if the deprecations would help ease documentation or makes it more complex though. But I wouldn't mind leaving doc strings for deprecated functionality out granted usage of the function called as specified by a GI generated doc string works in a backwards compatible way (similarly I think we should ignore arguments/doc overrides for deprecated GObject initializers). I was mostly thinking of functions returning (ok, result) which gets translated to result or None. For other stuff, please keep in mind that documentation can also be used for understanding old code, so I wouldn't just ignore and hide them. I'd prefer deprecation warnings in the docstring with instructions how to do it right in those cases. For overrides which strip boolean results, one approach could be to extend the replacement key idea and have a specialized version: %gi_doc_string_strip_boolean_result%. The strip_boolean_result() override helper could set this as the doc string on its returned function object. For cases where strip_boolean_result additionally raises, a Raises: annotation could be appended to to the doc string from the overrides side of things. In terms of deprecated overrides, I think what you've said sounds reasonable. For deprecated initializers, it should be fairly easy to generate informational doc strings within the init override helper (deprecated_init()), since it is passed all the relevant information. I was a bit overzealous with that statement. should just work is at least true in ipython standalone or integrated with eclipse/pydev (which is good enough for me at the moment). Eclipse nor Anjuta work for editor auto-completion with import hooks. At a cursory glance, Eclipse seems want to import the actual Python modules so there is some hope for this working in the editor. Anjuta uses python-rope which seems to use AST parsing and would be a more grave situation with import hooks. A little more reading of PEP302 reveals there was some talk about adding a list_modules method to the importer protocol which would potentially fix some of these problems, but it doesn't seem this has ever been added. Yeah, a possible solution is to create a fake package containing the whole API (Google gives me fakegir [0], but I haven't tried it). I think IDE integration deserves a page somewhere.. That is an interesting approach. The devhelp output wasn't really what I was expecting, which was style consistency of the html output. Style is fixable, it's just jinja templates. I could try to match the official css, but that's then another thing to maintain and sync of course. Disabling the sidebar and breadcrumbs should work for starters. I'm sure it is fixable one way or the other if we wanted to go there, but I think it is much less important than having accurate docs which include overrides. -Simon ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Python Docs (was Re: Coordination for developer documentations)
On Sat, Mar 8, 2014 at 9:15 AM, Christoph Reiter reiter.christ...@gmail.com wrote: On Sat, Mar 8, 2014 at 4:04 AM, Simon Feltman s.felt...@gmail.com wrote: * 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 terms of overrides having additional side effects beyond the intended GI API, I really hope we can deprecate those scenarios or additional arguments that invoke new/alternate behavior (like Gtk.MessageBox's buttons argument). It doesn't seem like there are very many of these cases and I'm not sure if the deprecations would help ease documentation or makes it more complex though. But I wouldn't mind leaving doc strings for deprecated functionality out granted usage of the function called as specified by a GI generated doc string works in a backwards compatible way (similarly I think we should ignore arguments/doc overrides for deprecated GObject initializers). * 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) That sounds like a good idea. A bit of bike-shedding, but I think a more explicit name would be nice. Something like %gi_doc_string_body% or variations on that which may or may not include argument documentation? * 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. Do you mean the doc generator could figure this out or that we make sure to manually add doc strings in these cases? Once I have this working with pgi, I will try to move the override changes needed to PyGObject. Sounds great. I would like to go through the existing override doc strings at some point and update them for better compatibility with Sphinx/reST. Would this be helpful or would it be in conflict with what you are thinking? (at least the Python only extensions like Property and Signal should be well formatted). * 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)? I was a bit overzealous with that statement. should just work is at least true in ipython standalone or integrated with eclipse/pydev (which is good enough for me at the moment). Eclipse nor Anjuta work for editor auto-completion with import hooks. At a cursory glance, Eclipse seems want to import the actual Python modules so there is some hope for this working in the editor. Anjuta uses python-rope which seems to use AST parsing and would be a more grave situation with import hooks. A little more reading of PEP302 reveals there was some talk about adding a list_modules method to the importer protocol which would potentially fix some of these problems, but it doesn't seem this has ever been added. * 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. Same problem as above I guess. Also this approach might not be that great if different people try to re-generate the html docs (in the context of building docs for hosting). You might get a different set of docs from the previous generation due to a different set of installed typelib/gir files. In which case managing an explicit
Re: Python Docs (was Re: Coordination for developer documentations)
On Sat, Mar 8, 2014 at 1:52 AM, John Stowers john.stowers.li...@gmail.com wrote: 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. Yep, Christoph's (lazka) API docs are what we are talking about and they are indeed fantastic :) I wasn't aware of learngtk.org, thanks for the link. 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). I don't really have much of an opinion as to where a consolation is located, but I am happy there is interest in this. It seems we have plenty of content available, it's just a bit fragmented (essentially what the parent thread is about, just from a larger perspective). Ekaterina mentioned developer.gnome.org, which sounds good, but I hope we can also have a consolidated portal of all things GNOME+Python to ease the developer experience from the perspective of a Python programmer. That could also just mean a page of links back to developer.gnome.org or external sources (which is what the PyGObject wiki [1] attempts). -Simon [1] https://wiki.gnome.org/Projects/PyGObject ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Python Docs (was Re: Coordination for developer documentations)
On Fri, Mar 7, 2014 at 3:22 AM, Christoph Reiter reiter.christ...@gmail.com wrote: On Thu, Mar 6, 2014 at 11:37 AM, Ekaterina Gerasimova kittykat3...@gmail.com wrote: On 6 March 2014 10:07, Christoph Reiter reiter.christ...@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 ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Possible to fix glaring Gjs API issues before GNOME 4?
On Thu, Feb 28, 2013 at 12:04 AM, Martin Pitt martin.p...@ubuntu.comwrote: Nikita Churaev [2013-02-27 23:26 +0400]: 3. Gtk.TextBuffer.set_text(text, length) --- length argument is useless, since JavaScript uses UTF-16 and length expects length of UTF-8 string. I'm afraid we have to live with little oddities like this. I think it's better to stay compatible with the C API and its documentation, and all currently existing JavaScript program which use the API than breaking API and continuously chasing after weird cases like that. I don't think skipping the length arg in this case could work even if API breakage was acceptable. I assume a skip implies a value of zero is used and in this case that would not work. A better alternative would be default value support. This way the oddity can be avoided in client code without breaking API and in general would be a very nice feature. However, new code using this would need to specify it only works with advanced versions of GLib or the libraries providing defaults. https://bugzilla.gnome.org/show_bug.cgi?id=558620 -Simon ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
