Re: RFC: documentation browser

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.

Where can I find the source for these manually written docs?

There is also lots of Gtk-doc prose that I think should eventually be incorporated: for example the GObject tutorial [1].

It is certainly possible to manually edit the output of g-ir-doc-tool before it is fed into DevDocs, but I would advocate at least some automatic step here.
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.

You are right; I thought I had fixed that already, but I just checked Gio.File.load_contents(), for example, and the parameters are not correct.

Can you give me an example of an array parameter that is wrong?

Thanks for the feedback,


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