search

pygobject / pgi-docgen

API Documentation Generator for PyGObject
https://lazka.github.io/pgi-docs/
GNU Lesser General Public License v2.1
127 stars 36 forks source link

documentation extensions(?) #163

Open ejmg opened 6 years ago

ejmg commented 6 years ago

Hi there

From what I understand, the documentation in this repository is generated automatically. However, there have been quite a few cases where I, as a new user of gi and Gtk generally, wasted 20-40 mins because of using the wrong function or class. This was/is due to the current state of Gtk documentation and I understand how hard that can be to maintain.

Nevertheless, I think many of the cases I experienced could be classified as beginner traps and easily mitigated with a one or two line "FYI" sentence at the end of docstrings for functions/classes that tripped me (and probably others) up.

Is there any chance we could add such "disclaimers" into the documentation? I feel such an addition would be a lot more useful than, say, me writing a blog post with lessons learned from developing my current Gtk app. I also feel this is more useful than scanning for gi related posts on stack overflow, which often are either massively outdated or are about gtk directly and not python's bindings.

I am interested in helping make documentation better if possible and don't know where else to posit my idea, so thank you for your time!

ejmg commented 6 years ago

I realize now that the code this repo pulls from is actually on gitlab and am feeling silly. Should I open an issue over there? I would like to add to the docs if I'm allowed!

lazka commented 6 years ago

I realize now that the code this repo pulls from is actually on gitlab and am feeling silly. Should I open an issue over there? I would like to add to the docs if I'm allowed!

This is the right place. Only pygobject itself is on gitlab atm.

lazka commented 6 years ago

Hi there

From what I understand, the documentation in this repository is generated automatically. However, there have been quite a few cases where I, as a new user of gi and Gtk generally, wasted 20-40 mins because of using the wrong function or class. This was/is due to the current state of Gtk documentation and I understand how hard that can be to maintain.

The docs are currently split into three part, mostly:

Nevertheless, I think many of the cases I experienced could be classified as beginner traps and easily mitigated with a one or two line "FYI" sentence at the end of docstrings for functions/classes that tripped me (and probably others) up.

If the FYI is not Python specific it could/should go into the C documentation of the library so everyone benefits. We currently don't have anything in place for changing the docstrings besides for Python overrides.

Can you give an example maybe?

Is there any chance we could add such "disclaimers" into the documentation? I feel such an addition would be a lot more useful than, say, me writing a blog post with lessons learned from developing my current Gtk app. I also feel this is more useful than scanning for gi related posts on stack overflow, which often are either massively outdated or are about gtk directly and not python's bindings.

What would the disclaimer be about roughly?

I am interested in helping make documentation better if possible and don't know where else to posit my idea, so thank you for your time!

Thanks!

ejmg commented 6 years ago

The docs are currently split into three part, mostly:

The docs I am talking about are the latter two, but primarily the auto-docs generated. That said, I would absolutely love to write an extension or two for gtk+ specific manual because

  1. it has helped me greatly :slightly_smiling_face:
  2. my current application (still heavily under work) uses concepts not currently covered but that I'm sure others would commonly come across.

If the FYI is not Python specific it could/should go into the C documentation of the library so everyone benefits. We currently don't have anything in place for changing the docstrings besides for Python overrides.

Can you give an example maybe?

So I guess I am a little confused over where the documentation "problem" is. This confusion may also determine whether I should just be writing up extensions to the gtk+ manual or to the auto-docs.

Let me give an example as you have asked. I have experienced the following around 2-3 times with various little snippets of code, but here is what I most recently struggled with:

I have a widget, textEntryBox that I would like to attach a callback to for when a user presses the ENTER key (aka RETURN afaict). The gtk+ manual does not cover such a problem, so I go to the auto-docs. It is here that I find Gtk's signal_key_press_event. From here, the documentation for the signal states:

To receive this signal, the Gdk.Window associated to the widget needs to enable the Gdk.EventMask.KEY_PRESS_MASK mask.

This sends me on a 20ish minute excursion into Gdk and, from what I could find online, nearly convinces me that I am going to have to deal with Gdk windows directly so that I can properly manage the EventMask I need, etcetera. I am luckily not too stupid and convince myself to keep scanning through Gtk's docs until I find Gtk.EventBox(). This is exactly what I needed and immediately solves my problem with respect to Gdk's windows, attaching one to a Gdk.Window-less widget, the relevant EventMask, and so forth.

What would the disclaimer be about roughly?

Using my example above, I am not sure this warrants an editing of the c code itself. I think you would probably know where this is best done. What this disclaimer would look like is pretty simple, though. I just think a sentence along the lines of "If you are managing low level events, such as key presses, through GTK, you probably are looking for Gtk.EventBox()"

Such a disclaimer (for other functions/classes) are already often found in the auto-gen docs and have personally saved me lots of time. Where they are do not immediately come to mind, but I am grateful for where I have seen them in my journey across the documentation :slightly_smiling_face:

lazka commented 6 years ago

On your specific problem/experience:

The gtk documentation might be helpful: https://developer.gnome.org/gtk3/stable/chap-input-handling.html#event-masks Event masks have always been confusing, as they are needed because how gtk uses/used X11 and not because the API adds anything for the user. I think event mask (and widget windows) will go away in gtk4, so this should be easier there at least.

ejmg commented 6 years ago

I think all three of your points are good ideas. Would you like assistance on any of these?