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: Coordination for developer documentations
On 7 March 2014 17:45, meg ford meg...@gmail.com wrote: It would also be awesome if whoever takes the lead on this makes sure that the functionality we are documenting actually works. If we want devs to be able to write GNOME apps then having documentation that matches the functionality they can access using the the language application developer docs are showing seems pretty key to me. Sure, this is one of the main motivations for rebasing the documentation generator on top of introspection data. Regards, Tomeu On Fri, Mar 7, 2014 at 8:06 AM, Tomeu Vizoso to...@sugarlabs.org wrote: On 4 March 2014 16:58, Frederic Peters fpet...@gnome.org wrote: Hey, It's been proved again in recent hackfests, we have a really great team writing user documentations, and thanks have to be given to Shaun, and now Kat, for coordinating the effort. On the other hand we have absolutely no coordination for developer docs, I maintain developer.gnome.org with the little time I have, Aleksander helps with Devhelp, there are some punctual changes from various persons, David maintains gnome-devel-docs, Tomeu did work on generating python documentation from gobject-introspection a while ago, Giovanni did it for gjs recently, Jon improved markdown support in gtk-doc, etc. but all this happens without coordination and it happens people step on each other's toes, and it hurts. Developer documentation will be a topic during the Developer Experience Hackfest, but I believe we will fail again to provide lasting effects if nobody takes on a coordination role. I agree coordination is needed right now. I have signed up for the hackfest because I know that there's still lots of work to do in the api doc generator and I would like to put my experience on the existing codebase to good use. But I'm a bit lost since the decisions that were agreed at the Berlin hackfest seem to have been overridden at some point and I have missed the rationale. So, are you interested? These days I do stuff that is related only peripherally to GNOME, so I'm afraid that I won't find enough time to take on the coordination. If nobody gets to propose a good plan before, I guess we'll have to have a good planning session at the start of the hackfest. Regards, Tomeu Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ 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)
Stefan Sauer wrote: On 03/08/2014 06:15 PM, Christoph Reiter wrote: 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. Indeed, the pages rendered by devhelp are HTML pages taken straight from the filesystem, with no transformation at all. As I wrote to Giovanni earlier, it would certainly be possible to reuse YelpView, to get support for Mallard files. Next to the document view, for the tree of documents and the keyword search, devhelp requires a file in its own '.devhelp2' xml format; it's actually quite simple, it goes like this: ?xml version=1.0 encoding=utf-8 standalone=no? book xmlns=http://www.devhelp.net/book; title=GTK+ 3 Reference Manual link=index.html author= name=gtk3 version=2 language=c chapters sub name=GTK+ Overview link=gtk.html sub name=Getting Started with GTK+ link=gtk-getting-started.html sub name=Basics link=gtk-getting-started.html#id-1.2.3.3/ ... /chapters functions !-- functions -- keyword type=function name=gtk_dialog_run() link=GtkDialog.html#gtk-dialog-run/ !-- but also other types keyword type=struct name=struct GtkApplicationClass link=GtkApplication.html#GtkApplicationClass/ !-- possibility to mention when it got added -- keyword type=enum name=enum GtkApplicationInhibitFlags link=GtkApplication.html#GtkApplicationInhibitFlags since=3.4/ !-- and also when it got deprecated -- keyword type=function name=gtk_dialog_set_alternative_button_order() link=GtkDialog.html#gtk-dialog-set-alternative-button-order deprecated=3.10: Deprecated since=2.6/ Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On 7 March 2014 17:45, meg ford meg...@gmail.com wrote: It would also be awesome if whoever takes the lead on this makes sure that the functionality we are documenting actually works. If we want devs to be able to write GNOME apps then having documentation that matches the functionality they can access using the the language application developer docs are showing seems pretty key to me. Sure, this is one of the main motivations for rebasing the documentation generator on top of introspection data. There are situations where bindings exist and in fact the functions don't work or the return values need to be accessed in odd ways (for example as by array index). Of course having the documentation is helpful because at least you don't have to mentally translate from C or read the raw gir files in order to figure out if the function should work, but there are some situations in which the documentation will need to be altered to reflect the reality. Regards, Tomeu On Fri, Mar 7, 2014 at 8:06 AM, Tomeu Vizoso to...@sugarlabs.org wrote: On 4 March 2014 16:58, Frederic Peters fpet...@gnome.org wrote: Hey, It's been proved again in recent hackfests, we have a really great team writing user documentations, and thanks have to be given to Shaun, and now Kat, for coordinating the effort. On the other hand we have absolutely no coordination for developer docs, I maintain developer.gnome.org with the little time I have, Aleksander helps with Devhelp, there are some punctual changes from various persons, David maintains gnome-devel-docs, Tomeu did work on generating python documentation from gobject-introspection a while ago, Giovanni did it for gjs recently, Jon improved markdown support in gtk-doc, etc. but all this happens without coordination and it happens people step on each other's toes, and it hurts. Developer documentation will be a topic during the Developer Experience Hackfest, but I believe we will fail again to provide lasting effects if nobody takes on a coordination role. I agree coordination is needed right now. I have signed up for the hackfest because I know that there's still lots of work to do in the api doc generator and I would like to put my experience on the existing codebase to good use. But I'm a bit lost since the decisions that were agreed at the Berlin hackfest seem to have been overridden at some point and I have missed the rationale. So, are you interested? These days I do stuff that is related only peripherally to GNOME, so I'm afraid that I won't find enough time to take on the coordination. If nobody gets to propose a good plan before, I guess we'll have to have a good planning session at the start of the hackfest. Regards, Tomeu Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
Frederic Peters fpet...@gnome.org wrote: ... Developer documentation will be a topic during the Developer Experience Hackfest, but I believe we will fail again to provide lasting effects if nobody takes on a coordination role. ... But I'm a bit lost since the decisions that were agreed at the Berlin hackfest seem to have been overridden at some point and I have missed the rationale. Right: continuity seems to be one of the main issues we've had in recent years. Contrary plans have been made at various hackfests, often by separate or partially overlapping groups of people. We've also had individuals come in, make changes and then move on to other things. The Dev X hackfest will be a great opportunity to deal with some of this. We've made an effort to get a wide range of participants at the upcoming Dev X hackfest, including members of the documentation and GTK+ teams, so it will hopefully be a chance for everyone to get on the same page. We should also make sure that we agree on a single place to keep our documentation plans, so we don't keep reinventing the wheel each time. So, are you interested? I can see coordination happening at a few levels. As already mentioned, we need a shared plan. This will need to include things like: 1. Designs for developer.gnome.org. 2. A structure and format for handwritten tutorials. 3. API reference documentation roadmap. One really positive thing we can do is agree on a single place to keep designs and plans for developer docs, possibly in a new space on the wiki. We should also talk about when and how to update these plans, so that everyone is kept in the loop. To be honest, a large part of the coordination burden needs to fall on the people who are working on the toolkit - since they know how the platform is developing, they need to be able to update the handwritten docs or indicate when things need updating or adding. In short: any plan we come up with will have to address how we are going to close the gap between platform and docs. Allan ___ 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 Sun, Mar 9, 2014 at 11:35 PM, Stefan Sauer enso...@hora-obscura.de wrote: 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. OK, thanks for the clarification ___ 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 Mon, Mar 10, 2014 at 4:27 AM, Simon Feltman s.felt...@gmail.com wrote: 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). 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. * 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? Sure. * 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? No, that needs be done manually somehow. Sphinx already supports such function signature overrides in docstrings (for C extensions I guess), but that clashes with the signature pgi exposes for type information, so I need to find another way. 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). Sure, that would be helpful. * 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. Yeah, a possible solution is to create a fake package containing the whole API (Google gives me fakegir [0], but I haven't
Re: Coordination for developer documentations
On 03/08/2014 02:31 AM, Alberto Ruiz wrote: Pull requests are not encouraged, we tell anyone that tries one to go to Bugzilla/ML and we cancel it. I see. The pull requests would lower the barrier to fix docs. Stefan 2014-03-07 22:58 GMT+01:00 Stefan Sauer enso...@hora-obscura.de mailto:enso...@hora-obscura.de: On 03/06/2014 05:41 PM, Sébastien Wilmet wrote: On Tue, Mar 04, 2014 at 07:05:30PM +0100, Frederic Peters wrote: I was mostly concerned by our technical infrastructure for developer documentation, but that itself has of course been driven by the content we produced (or wanted to produce), so I don't think they can really be separated. For the content, what is really needed in my opinion is a good and recent book on GLib and GTK+. GTK+ 3 is maybe too unstable for writing a book, but GLib (including GObject and GIO) is stable enough. It could be a simple update of an existing book, such as The Official GNOME 2 Developer's Guide. The book should also be freely available on the web, with a free license (Creative Commons for example). If the book focus on the C language, it makes sense to write also chapters on how to write good libraries, how to design good APIs with GObject, what are the best practices, etc. This is something less well documented. And this can also be beneficial for internal code in applications, not just libraries. Another thing, I see sometimes on IRC some questions about how to use a certain API, or questions on some details not documented. Ideally when such a question is answered, the API documentation should be improved at the same time, so it benefits other people. I don't know if such small improvements are often done, but if everybody takes the time to write patches for the documentation when a problem is encountered, the documentation will get better over the time. As the gnome modules are now mirrored to github, one should be able to fork them there, do edits on the web and send a pull request. Given that module maintainers follow the mirrored modules though. Stefan Best regards, Sébastien ___ desktop-devel-list mailing list desktop-devel-list@gnome.org mailto:desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org mailto:desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On Sun, Mar 9, 2014 at 11:54 AM, Stefan Sauer enso...@hora-obscura.dewrote: I see. The pull requests would lower the barrier to fix docs. There was a lengthy discussion of this on the foundation-list last August, and a follow-up email from Karen in September regarding the Board's decision [1]. Meg [1] https://mail.gnome.org/archives/foundation-list/2013-September/msg4.html ___ 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 03/08/2014 06:15 PM, Christoph Reiter wrote: On Sat, Mar 8, 2014 at 4:04 AM, Simon Feltman s.felt...@gmail.com 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
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)
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 s.felt...@gmail.com wrote: 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 ___ 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 4:04 AM, Simon Feltman s.felt...@gmail.com 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
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
Re: Coordination for developer documentations
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. There doesn't seem to be a dedicated IRC channel, so I'm idling in #docs-devel now At the moment, we use #docs for everything. OK, thanks. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On 4 March 2014 16:58, Frederic Peters fpet...@gnome.org wrote: Hey, It's been proved again in recent hackfests, we have a really great team writing user documentations, and thanks have to be given to Shaun, and now Kat, for coordinating the effort. On the other hand we have absolutely no coordination for developer docs, I maintain developer.gnome.org with the little time I have, Aleksander helps with Devhelp, there are some punctual changes from various persons, David maintains gnome-devel-docs, Tomeu did work on generating python documentation from gobject-introspection a while ago, Giovanni did it for gjs recently, Jon improved markdown support in gtk-doc, etc. but all this happens without coordination and it happens people step on each other's toes, and it hurts. Developer documentation will be a topic during the Developer Experience Hackfest, but I believe we will fail again to provide lasting effects if nobody takes on a coordination role. I agree coordination is needed right now. I have signed up for the hackfest because I know that there's still lots of work to do in the api doc generator and I would like to put my experience on the existing codebase to good use. But I'm a bit lost since the decisions that were agreed at the Berlin hackfest seem to have been overridden at some point and I have missed the rationale. So, are you interested? These days I do stuff that is related only peripherally to GNOME, so I'm afraid that I won't find enough time to take on the coordination. If nobody gets to propose a good plan before, I guess we'll have to have a good planning session at the start of the hackfest. Regards, Tomeu Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
It would also be awesome if whoever takes the lead on this makes sure that the functionality we are documenting actually works. If we want devs to be able to write GNOME apps then having documentation that matches the functionality they can access using the the language application developer docs are showing seems pretty key to me. On Fri, Mar 7, 2014 at 8:06 AM, Tomeu Vizoso to...@sugarlabs.org wrote: On 4 March 2014 16:58, Frederic Peters fpet...@gnome.org wrote: Hey, It's been proved again in recent hackfests, we have a really great team writing user documentations, and thanks have to be given to Shaun, and now Kat, for coordinating the effort. On the other hand we have absolutely no coordination for developer docs, I maintain developer.gnome.org with the little time I have, Aleksander helps with Devhelp, there are some punctual changes from various persons, David maintains gnome-devel-docs, Tomeu did work on generating python documentation from gobject-introspection a while ago, Giovanni did it for gjs recently, Jon improved markdown support in gtk-doc, etc. but all this happens without coordination and it happens people step on each other's toes, and it hurts. Developer documentation will be a topic during the Developer Experience Hackfest, but I believe we will fail again to provide lasting effects if nobody takes on a coordination role. I agree coordination is needed right now. I have signed up for the hackfest because I know that there's still lots of work to do in the api doc generator and I would like to put my experience on the existing codebase to good use. But I'm a bit lost since the decisions that were agreed at the Berlin hackfest seem to have been overridden at some point and I have missed the rationale. So, are you interested? These days I do stuff that is related only peripherally to GNOME, so I'm afraid that I won't find enough time to take on the coordination. If nobody gets to propose a good plan before, I guess we'll have to have a good planning session at the start of the hackfest. Regards, Tomeu Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On 03/06/2014 05:41 PM, Sébastien Wilmet wrote: On Tue, Mar 04, 2014 at 07:05:30PM +0100, Frederic Peters wrote: I was mostly concerned by our technical infrastructure for developer documentation, but that itself has of course been driven by the content we produced (or wanted to produce), so I don't think they can really be separated. For the content, what is really needed in my opinion is a good and recent book on GLib and GTK+. GTK+ 3 is maybe too unstable for writing a book, but GLib (including GObject and GIO) is stable enough. It could be a simple update of an existing book, such as The Official GNOME 2 Developer's Guide. The book should also be freely available on the web, with a free license (Creative Commons for example). If the book focus on the C language, it makes sense to write also chapters on how to write good libraries, how to design good APIs with GObject, what are the best practices, etc. This is something less well documented. And this can also be beneficial for internal code in applications, not just libraries. Another thing, I see sometimes on IRC some questions about how to use a certain API, or questions on some details not documented. Ideally when such a question is answered, the API documentation should be improved at the same time, so it benefits other people. I don't know if such small improvements are often done, but if everybody takes the time to write patches for the documentation when a problem is encountered, the documentation will get better over the time. As the gnome modules are now mirrored to github, one should be able to fork them there, do edits on the web and send a pull request. Given that module maintainers follow the mirrored modules though. Stefan Best regards, Sébastien ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
Pull requests are not encouraged, we tell anyone that tries one to go to Bugzilla/ML and we cancel it. 2014-03-07 22:58 GMT+01:00 Stefan Sauer enso...@hora-obscura.de: On 03/06/2014 05:41 PM, Sébastien Wilmet wrote: On Tue, Mar 04, 2014 at 07:05:30PM +0100, Frederic Peters wrote: I was mostly concerned by our technical infrastructure for developer documentation, but that itself has of course been driven by the content we produced (or wanted to produce), so I don't think they can really be separated. For the content, what is really needed in my opinion is a good and recent book on GLib and GTK+. GTK+ 3 is maybe too unstable for writing a book, but GLib (including GObject and GIO) is stable enough. It could be a simple update of an existing book, such as The Official GNOME 2 Developer's Guide. The book should also be freely available on the web, with a free license (Creative Commons for example). If the book focus on the C language, it makes sense to write also chapters on how to write good libraries, how to design good APIs with GObject, what are the best practices, etc. This is something less well documented. And this can also be beneficial for internal code in applications, not just libraries. Another thing, I see sometimes on IRC some questions about how to use a certain API, or questions on some details not documented. Ideally when such a question is answered, the API documentation should be improved at the same time, so it benefits other people. I don't know if such small improvements are often done, but if everybody takes the time to write patches for the documentation when a problem is encountered, the documentation will get better over the time. As the gnome modules are now mirrored to github, one should be able to fork them there, do edits on the web and send a pull request. Given that module maintainers follow the mirrored modules though. Stefan Best regards, Sébastien ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Cheers, Alberto Ruiz ___ 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: Coordination for developer documentations
(responding to the wrong mail since I just subscribed and don't bother modifying mail headers..) 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. There doesn't seem to be a dedicated IRC channel, so I'm idling in #docs-devel now [0] http://python-gtk-3-tutorial.readthedocs.org [1] http://github.com/sebp/PyGObject-Tutorial/issues/35 [2] http://lazka.github.io/pgi-docs/api/Gtk_3.0/classes/Container.html ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On 6 March 2014 10:07, Christoph Reiter reiter.christ...@gmail.com wrote: (responding to the wrong mail since I just subscribed and don't bother modifying mail headers..) 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? There doesn't seem to be a dedicated IRC channel, so I'm idling in #docs-devel now At the moment, we use #docs for everything. [0] http://python-gtk-3-tutorial.readthedocs.org [1] http://github.com/sebp/PyGObject-Tutorial/issues/35 [2] http://lazka.github.io/pgi-docs/api/Gtk_3.0/classes/Container.html [3] https://wiki.gnome.org/Hackfests/DeveloperExperience2014 ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On 03/04/2014 07:05 PM, Frederic Peters wrote: Hi Allan, Allan Day wrote: So, are you interested? It would help to know a bit more about what you think this coordination role would involve. Are you concerned with keeping technical changes in step, for example, or is it more the content in our hand written documentation that we need to be careful about? I was mostly concerned by our technical infrastructure for developer documentation, but that itself has of course been driven by the content we produced (or wanted to produce), so I don't think they can really be separated. A recent example is the way gtk-doc comments are written, and how to accomodate them in order to provide meaningful comments when reused for other languages (references to manual memory management for example). I am trying to keep the gtk-doc manual up-to-date, also wrt to how to document things. Bug report and patches are very welcome. I know that wikis are easier to edit, but imho they are harder to find and less often reviewed. Maybe the concerned parties just need to be made aware of how their work might affect others? Or maybe the dependencies between components need to be more clearly spelled out? Given a vision I believe it will be necessary to coordinate whatever needs to be done to get to it, having various persons giving the subject a bit of their time sporadically won't work out (that's what we've been doing since at least the Berlin hackfest more than four years ago). Maybe we do not need a person, maybe tools (like the gnome-devel-doc list) are enough to get the required coordination, but from what I've seen of the documentation team, a dedicated and focused person really helps. So I agree with you, the first is certainly to get that common vision nailed down. But then, having a solid developer documentation team, rather than various individuals, would help tremendously, in defining the vision, and working towards it afterwards. +1 for this. Someone overlooking this and making sure that efforts are coordinated would be great. Stefan Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On Tue, Mar 4, 2014, at 10:54 AM, Jasper St. Pierre wrote: The issue seems to be that people show up, write a bunch of tutorials, docs, build a website, and then never finish it. They just leave and we're left with a half-finished developer docs site. It's been great seeing this happen at the hands of interns at various hackfests, but very few of them stick around. It was also a little disenheartening last year to see work being done by two teams, in two directions, with no overlap, at three successive events; members of both teams didn't meet until GUADEC. Coordination would hopefully mean more continuity in generating the content. Mike ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On Wed, Mar 5, 2014 at 2:20 PM, Michael Hill mdhil...@fastmail.fm wrote: On Tue, Mar 4, 2014, at 10:54 AM, Jasper St. Pierre wrote: The issue seems to be that people show up, write a bunch of tutorials, docs, build a website, and then never finish it. They just leave and we're left with a half-finished developer docs site. It's been great seeing this happen at the hands of interns at various hackfests, but very few of them stick around. It was also a little disenheartening last year to see work being done by two teams, in two directions, with no overlap, at three successive events; members of both teams didn't meet until GUADEC. Coordination would hopefully mean more continuity in generating the content. We need a project coordinator! :-) Volunteers! they don't really need to know what the topic is, just the fact that they can coordinate them. sri Mike ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Coordination for developer documentations
Hey, It's been proved again in recent hackfests, we have a really great team writing user documentations, and thanks have to be given to Shaun, and now Kat, for coordinating the effort. On the other hand we have absolutely no coordination for developer docs, I maintain developer.gnome.org with the little time I have, Aleksander helps with Devhelp, there are some punctual changes from various persons, David maintains gnome-devel-docs, Tomeu did work on generating python documentation from gobject-introspection a while ago, Giovanni did it for gjs recently, Jon improved markdown support in gtk-doc, etc. but all this happens without coordination and it happens people step on each other's toes, and it hurts. Developer documentation will be a topic during the Developer Experience Hackfest, but I believe we will fail again to provide lasting effects if nobody takes on a coordination role. So, are you interested? Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
Frederic Peters fpet...@gnome.org wrote: ... It's been proved again in recent hackfests, we have a really great team writing user documentations, and thanks have to be given to Shaun, and now Kat, for coordinating the effort. On the other hand we have absolutely no coordination for developer docs, I maintain developer.gnome.org with the little time I have, Aleksander helps with Devhelp, there are some punctual changes from various persons, David maintains gnome-devel-docs, Tomeu did work on generating python documentation from gobject-introspection a while ago, Giovanni did it for gjs recently, Jon improved markdown support in gtk-doc, etc. but all this happens without coordination and it happens people step on each other's toes, and it hurts. Developer documentation will be a topic during the Developer Experience Hackfest, but I believe we will fail again to provide lasting effects if nobody takes on a coordination role. From my point of view, the main thing we need right now is a shared vision for where we are trying to get to. Thankfully there are a lot of excellent ideas circulating about this, and the upcoming hackfest will be a great opportunity to come up with a plan we can all work towards. This should hopefully help to reduce coordination issues. So, are you interested? It would help to know a bit more about what you think this coordination role would involve. Are you concerned with keeping technical changes in step, for example, or is it more the content in our hand written documentation that we need to be careful about? Maybe the concerned parties just need to be made aware of how their work might affect others? Or maybe the dependencies between components need to be more clearly spelled out? Allan ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
Hi Allan, Allan Day wrote: So, are you interested? It would help to know a bit more about what you think this coordination role would involve. Are you concerned with keeping technical changes in step, for example, or is it more the content in our hand written documentation that we need to be careful about? I was mostly concerned by our technical infrastructure for developer documentation, but that itself has of course been driven by the content we produced (or wanted to produce), so I don't think they can really be separated. A recent example is the way gtk-doc comments are written, and how to accomodate them in order to provide meaningful comments when reused for other languages (references to manual memory management for example). Maybe the concerned parties just need to be made aware of how their work might affect others? Or maybe the dependencies between components need to be more clearly spelled out? Given a vision I believe it will be necessary to coordinate whatever needs to be done to get to it, having various persons giving the subject a bit of their time sporadically won't work out (that's what we've been doing since at least the Berlin hackfest more than four years ago). Maybe we do not need a person, maybe tools (like the gnome-devel-doc list) are enough to get the required coordination, but from what I've seen of the documentation team, a dedicated and focused person really helps. So I agree with you, the first is certainly to get that common vision nailed down. But then, having a solid developer documentation team, rather than various individuals, would help tremendously, in defining the vision, and working towards it afterwards. Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
The issue seems to be that people show up, write a bunch of tutorials, docs, build a website, and then never finish it. They just leave and we're left with a half-finished developer docs site. Usually, the tutorials that these guys write end up not compiling or running in newer versions of the GNOME development stack. So, we need to be testing them better. Having such tutorials somewhere in some git repo so they can be easily tested would be a huge help. Matthias's application1-10 he did for the last GUADEC were excellent, but they're not quite beginner enough. While I'd love to step up and do this, I'm remarkably busy as a person, and honestly, most of my free time is actually playing around with the web technology stack, not ours. It's a lot more exciting, and has a lot more fast-developing and approachable features. (This last weekend I wrote some a simple 3D pong clone using WebGL, and then made it into a rhythm game with a dynamic sequencer using the Web Audio APIs. This sort of tech is ten times more exciting than whatever's coming in GTK+ next cycle, and I prefer to play with fun tech in my free time.) On Tue, Mar 4, 2014 at 1:05 PM, Frederic Peters fpet...@gnome.org wrote: Hi Allan, Allan Day wrote: So, are you interested? It would help to know a bit more about what you think this coordination role would involve. Are you concerned with keeping technical changes in step, for example, or is it more the content in our hand written documentation that we need to be careful about? I was mostly concerned by our technical infrastructure for developer documentation, but that itself has of course been driven by the content we produced (or wanted to produce), so I don't think they can really be separated. A recent example is the way gtk-doc comments are written, and how to accomodate them in order to provide meaningful comments when reused for other languages (references to manual memory management for example). Maybe the concerned parties just need to be made aware of how their work might affect others? Or maybe the dependencies between components need to be more clearly spelled out? Given a vision I believe it will be necessary to coordinate whatever needs to be done to get to it, having various persons giving the subject a bit of their time sporadically won't work out (that's what we've been doing since at least the Berlin hackfest more than four years ago). Maybe we do not need a person, maybe tools (like the gnome-devel-doc list) are enough to get the required coordination, but from what I've seen of the documentation team, a dedicated and focused person really helps. So I agree with you, the first is certainly to get that common vision nailed down. But then, having a solid developer documentation team, rather than various individuals, would help tremendously, in defining the vision, and working towards it afterwards. Fred ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list -- Jasper ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On Tue, Mar 4, 2014 at 10:54 AM, Jasper St. Pierre jstpie...@mecheye.net wrote: The issue seems to be that people show up, write a bunch of tutorials, docs, build a website, and then never finish it. They just leave and we're left with a half-finished developer docs site. This is very true and I have pointed this out from time to time. Usually, the tutorials that these guys write end up not compiling or running in newer versions of the GNOME development stack. So, we need to be testing them better. We've spun up a QA Team, this could be one of those things to test as part of the release. Some of it can be automated, some of those could be hand tested, it all depends. The QA team will be an excellent place for new contributors to start since hte barrier of entry is quite low. The release team could then decide the quality of the release based on whether everything is working including tutorials as part of it's purview of readying a release. Having such tutorials somewhere in some git repo so they can be easily tested would be a huge help. Could be part of gnome-continuous. I think Colin talked about it as well and that it could be easily done. Matthias's application1-10 he did for the last GUADEC were excellent, but they're not quite beginner enough. The more the merrier. While I'd love to step up and do this, I'm remarkably busy as a person, and honestly, most of my free time is actually playing around with the web technology stack, not ours. It's a lot more exciting, and has a lot more fast-developing and approachable features. Just had to throw that out there, didn't you? :D You should look at https://crosswalk-project.org/. sri ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: Coordination for developer documentations
On Tue, 2014-03-04 at 13:47 -0800, Sriram Ramkrishna wrote: On Tue, Mar 4, 2014 at 10:54 AM, Jasper St. Pierre jstpie...@mecheye.net wrote: The issue seems to be that people show up, write a bunch of tutorials, docs, build a website, and then never finish it. They just leave and we're left with a half-finished developer docs site. This is very true and I have pointed this out from time to time. Usually, the tutorials that these guys write end up not compiling or running in newer versions of the GNOME development stack. So, we need to be testing them better. We've spun up a QA Team, this could be one of those things to test as part of the release. Some of it can be automated, some of those could be hand tested, it all depends. The QA team will be an excellent place for new contributors to start since hte barrier of entry is quite low. Just a quick interruption from myself, I'm happy to do a bit of spare time testing of the gnome continuous images, have several machines here I can test on. All I need is an agreed report format (spreadsheet?) and some links to get started tomorrow. - Ikey The release team could then decide the quality of the release based on whether everything is working including tutorials as part of it's purview of readying a release. Having such tutorials somewhere in some git repo so they can be easily tested would be a huge help. Could be part of gnome-continuous. I think Colin talked about it as well and that it could be easily done. Matthias's application1-10 he did for the last GUADEC were excellent, but they're not quite beginner enough. The more the merrier. While I'd love to step up and do this, I'm remarkably busy as a person, and honestly, most of my free time is actually playing around with the web technology stack, not ours. It's a lot more exciting, and has a lot more fast-developing and approachable features. Just had to throw that out there, didn't you? :D You should look at https://crosswalk-project.org/. sri ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list - Intel Corporation (UK) Limited Registered No. 1134945 (England) Registered Office: Pipers Way, Swindon SN3 1RJ VAT No: 860 2173 47 This e-mail and any attachments may contain confidential material for the sole use of the intended recipient(s). Any review or distribution by others is strictly prohibited. If you are not the intended recipient, please contact the sender and delete all copies. ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
