Re: RFC: documentation browser

[Giovanni Campagna <scampa giovanni gmail com>]

On Wed, Jan 6, 2016 at 9:33 AM, Jasper St. Pierre 
<jstpierre mecheye net> wrote:
> My opinion, which some of you know -- is that we should just get rid
> of the crazy overrides and just have helper modules for those.
> Gio.DBus is my least favorite of all of these.

The point of docs is not to make technical decisions, but to document 
the decisions that were already made. Gio.DBus is a reality today, and 
it's used by multiple projects. It's what maintainers of current gjs 
apps will expect newcomers will use in patches, and it should be 
documented.

I agree with you Gio.DBus was designed badly, but Gio.DBus2 was never 
merged and we all lost interest in it, so we're sticking with it.
Also, I don't agree that GObject.Class or Gtk.WidgetClass are bad, they 
do their job (with a few quirks, like signal overriding).

Cheers,

Giovanni

> On Wed, Jan 6, 2016 at 9:31 AM, Giovanni Campagna
> <scampa giovanni gmail com> wrote:
> >  Hi Philip!
> >
> >  On Tue, Jan 5, 2016 at 11:08 PM, philip chimento gmail com wrote:
> > >  Hi,
> > >
> > >  I've been working on a documentation browser for documentation 
> > > generated
> > >  from GObject introspection files. Besides good old DevHelp on the 
> > > desktop,
> > >  there are several good online open-source documentation browsers 
> > > that
> > >  already exist, and one of them is DevDocs [1] which has lots of 
> > > nifty
> > >  features such as fuzzy search and storing documentation for 
> > > offline use.
> > >
> > >  I have a branch of gobject-introspection [2] which modifies 
> > > g-ir-doc-tool
> > >  to generate docs that can then be imported by a branch of DevDocs 
> > > [3]. Among
> > >  the modifications to g-ir-doc-tool is a refactoring to give it an 
> > > output
> > >  format switch which I've already filed as bgo#750534 [4].
> > >
> > >  I've hosted an instance of the modified DevDocs on AWS [5]. This 
> > > link is
> > >  temporary, because at some point it'll start costing me money. I 
> > > also have
> > >  instructions [6] for how I set up DevDocs from a bare RHEL 7 
> > > install on AWS
> > >  in case anyone wants to replicate it themselves.
> > >
> > >  If you're interested in this, please give it a try and let me know 
> > > your
> > >  thoughts and suggestions. I'm hoping to get more people interested 
> > > in it,
> > >  especially with the upcoming DX hackfest.
> >
> >
> >  Thanks for working on this.
> >  Compared to my previous effort, but similar to other efforts, this 
> > lacks the
> >  manual docs that were written for GLib and GObject (eg 
> > GObject.Class,
> >  GObject.Void and GLib.Variant).
> >  What is the best way to bridge those documents to the new system? 
> > Is it
> >  possible to manually edit the output of the modified g-ir-doc-tool, 
> > at least
> >  for GLib, GObject? Gio (Gio.DBus) and Gtk (Gtk.WidgetClass override 
> > for
> >  templates) potentially need manual editing too.
> >  Also, it seems the parameter naming and listing is wrong/confusing 
> > for out
> >  parameters and for arrays (I haven't checked callbacks), which is 
> > surprising
> >  since g-ir-doc-tool should do the right thing. Unfortunately, those 
> > are the
> >  most painful points to understand when using gjs, so they need to be
> >  addressed before this goes public.
> >
> >  Cheers,
> >
> >  Giovanni
> >
> >
> >  _______________________________________________
> >  desktop-devel-list mailing list
> >  desktop-devel-list gnome org
> >  https://mail.gnome.org/mailman/listinfo/desktop-devel-list
>
>
>
> --
>   Jasper