Re: Python Docs (was Re: Coordination for developer documentations)



On Mon, Mar 10, 2014 at 7:48 AM, Christoph Reiter
<reiter christoph gmail com> wrote:
On Mon, Mar 10, 2014 at 4:27 AM, Simon Feltman <s feltman 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


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]