After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 625494 - [scanner] Add DocBook Generator
[scanner] Add DocBook Generator
Status: RESOLVED FIXED
Product: gobject-introspection
Classification: Platform
Component: g-ir-doctool
unspecified
Other Linux
: Normal enhancement
: ---
Assigned To: gobject-introspection Maintainer(s)
gobject-introspection Maintainer(s)
Depends on:
Blocks:
 
 
Reported: 2010-07-28 14:27 UTC by Zach Goldberg
Modified: 2018-01-25 15:37 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Set of patches to work on gidocgen (8.58 KB, application/x-gzip)
2010-07-28 14:28 UTC, Zach Goldberg
  Details
WIP doctool (15.16 KB, patch)
2011-02-01 19:42 UTC, Johan (not receiving bugmail) Dahlin
none Details | Review
WIP doctool (15.24 KB, patch)
2011-08-10 12:11 UTC, Tomeu Vizoso
none Details | Review

Description Zach Goldberg 2010-07-28 14:27:23 UTC
Uses the GIR to build docbook which can be turned into html via gtkdoc-mkhtml.
Comment 1 Zach Goldberg 2010-07-28 14:28:25 UTC
Created attachment 166714 [details]
Set of patches to work on gidocgen
Comment 2 Johan (not receiving bugmail) Dahlin 2011-02-01 19:42:09 UTC
Created attachment 179827 [details] [review]
WIP doctool

Work in progress, I refactored a big part of Zach's patches and updated
them to git HEAD.
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2011-02-01 21:49:24 UTC
Zach, are you aware of the plans on gtk-doc side to read git files instead of the output from gtkdoc-scan and gtkdoc-scanobj?

Would be good to discuss how to take this forward, I am on irc or the gtk-doc list (and elsewhere).
Comment 4 David Planella 2011-02-02 06:42:38 UTC
There is also this project doing something similar:
http://git.gnome.org/browse/introspection-doc-generator/

http://www.roojs.com/index.php/View/187/Generating_Seed_Documentation_from_Gobject_introspection.html

It might be worth talking to them and unifying development efforts.
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2011-05-11 08:10:05 UTC
Are the example outputs of the current tools online somewhere?
Comment 6 Tomeu Vizoso 2011-07-12 06:27:19 UTC
(In reply to comment #3)
> Zach, are you aware of the plans on gtk-doc side to read git files instead of
> the output from gtkdoc-scan and gtkdoc-scanobj?
> 
> Would be good to discuss how to take this forward, I am on irc or the gtk-doc
> list (and elsewhere).

Hi Stefan, will you be there at the Summit? We are planning to work on this during an introspection hackfest which will overlap with the BoFs, so would be great to have you there and hear about your plans.

Is there anything written about those plans? Couldn't find anything related in the gtk-doc mailing list archives.

My impression right now is that a good course of action could be making obsolete those pieces of gtk-doc that overlap with g-ir-scanner, by making gtk-doc consume directly .gir files.
Comment 7 Stefan Sauer (gstreamer, gtkdoc dev) 2011-07-12 18:01:58 UTC
(In reply to comment #6)
> (In reply to comment #3)
> > Zach, are you aware of the plans on gtk-doc side to read git files instead of
> > the output from gtkdoc-scan and gtkdoc-scanobj?
> > 
> > Would be good to discuss how to take this forward, I am on irc or the gtk-doc
> > list (and elsewhere).
> 
> Hi Stefan, will you be there at the Summit? We are planning to work on this
> during an introspection hackfest which will overlap with the BoFs, so would be
> great to have you there and hear about your plans.

I am trying to be at the desktop summit for the 9-10th Aug weekend. It's all in the flow as I am currently moving.

> Is there anything written about those plans? Couldn't find anything related in
> the gtk-doc mailing list archives.

http://live.gnome.org/DocumentationProject/GtkDocLanguageBindings

> My impression right now is that a good course of action could be making
> obsolete those pieces of gtk-doc that overlap with g-ir-scanner, by making
> gtk-doc consume directly .gir files.

That is indee on thing that could be done. I've put some thoughts here.
http://live.gnome.org/DocumentationProject/GtkDocGir
I will try to ask on desktop devel if a perl-xml module dependency on gtk-doc side would be a concern for any one.
Comment 8 Stefan Sauer (gstreamer, gtkdoc dev) 2011-07-12 18:15:09 UTC
(In reply to comment #7)
> (In reply to comment #6)
> > (In reply to comment #3)
> > > Zach, are you aware of the plans on gtk-doc side to read git files instead list (and elsewhere).
> > 
> > Hi Stefan, will you be there at the Summit? We are planning to work on this
> > during an introspection hackfest which will overlap with the BoFs, so would be
> > great to have you there and hear about your plans.
> 
> I am trying to be at the desktop summit for the 9-10th Aug weekend. It's all in
> the flow as I am currently moving.

erm. I mean 6-7th. Probably arrive on the evening of the 5th.
Comment 9 Tomeu Vizoso 2011-08-10 12:11:22 UTC
Created attachment 193542 [details] [review]
WIP doctool
Comment 10 Laszlo Pandy 2011-08-11 13:43:55 UTC
Now hacking this patch in gir-doctool branch of gobject-introspection.
Comment 11 John Stowers 2011-08-11 19:59:56 UTC
(In reply to comment #10)
> Now hacking this patch in gir-doctool branch of gobject-introspection.

Just a quick review of the code, forgive me I have not tested it.

I think it would be good if this could be used for the PyGObject docs, which means making it aware of wrappers etc higher in the stack. How about exporting parts of the docgen tool as public python API, and let registration of doc-transformers.

Then PyGObject could register a doc-transformer which substitutes or ammends the gir docs with those defined in the override function/class __doc__ strings.
Comment 12 Johan (not receiving bugmail) Dahlin 2011-08-11 20:29:22 UTC
I agree with John, there needs to be a way to override documentation generation similar to how we allow typelib functions/classes to be overriden.

Ideally we should use the same source, so we can just add docstrings to the overrides. Thanks for taking the time to report this bug.
Without a stack trace from the crash it's very hard to determine what caused it.
Can you get us a stack trace? Please see http://live.gnome.org/GettingTraces for more information on how to do so. Thanks in advance!
Comment 13 Javier Jardón (IRC: jjardon) 2012-08-20 09:34:31 UTC
Doctool wiki page: https://live.gnome.org/GObjectIntrospection/Doctools
Comment 14 André Klapper 2015-02-07 17:10:45 UTC
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
Comment 15 Emmanuele Bassi (:ebassi) 2018-01-25 15:37:32 UTC
The doctool is part of the introspection repository, now. Additional issues should be filed as separate bugs.