GNOME Bugzilla – Bug 625494
[scanner] Add DocBook Generator
Last modified: 2018-01-25 15:37:32 UTC
Uses the GIR to build docbook which can be turned into html via gtkdoc-mkhtml.
Created attachment 166714 [details] Set of patches to work on gidocgen
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.
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).
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.
Are the example outputs of the current tools online somewhere?
(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.
(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.
(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.
Created attachment 193542 [details] [review] WIP doctool
Now hacking this patch in gir-doctool branch of gobject-introspection.
(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.
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!
Doctool wiki page: https://live.gnome.org/GObjectIntrospection/Doctools
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
The doctool is part of the introspection repository, now. Additional issues should be filed as separate bugs.