Hi Suma,
On Wed, 2015-11-18 at 08:47 +0000, Suma Shanbhog (RBEI/ECF4) wrote:
The API documentations yes. But we are looking at creating a bigger level of documentation similar to what is available in other SDKs like ios, android etc. Where the starting point is not really the API. The developer should understand the which component to start with (as explained before, somebody new to our SDK will not know champlain is our map widget).
I completely agree.
I have sent a couple of mails before to the mailing list addressed to Kat. The question is if we should provide some overview for our SDK like here : https://wiki.gnome.org/Projects/Grilo Or Do we expect the developers to look it up on internet/wiki ? If yes, what format?
I don’t know what Kat has been planning for this, so let’s wait for her to respond on https://bugs.apertis.org/show_bug.cgi?id=579.
Philip
-----Original Message----- From: Philip Withnall [mailto:philip.withnall@collabora.co.uk] Sent: Wednesday, November 18, 2015 2:10 PM To: Suma Shanbhog (RBEI/ECF4); Barkowski Andre (CM-CI1/PRM1) Cc: devel@lists.apertis.org Subject: Re: [Devel] Preview of new documentation tool output
Hi Suma,
On Wed, 2015-11-18 at 05:22 +0000, Suma Shanbhog (RBEI/ECF4) wrote:
Hello Philip,
This sounds good. I had created a ticket in bugzilla for this very topic. bug 579 The ticket describes the requirements for documentation and requests for a solution. I see that you have already planned integrating Mallard with API documentation.
Thanks, I’ve subscribed to that. Let’s keep discussion there.
As we discussed long time back, this might be the way to go. But, there might be lot of documentation available online as well (for e.g for Geoclue) which should be integrated in our SDK. Please keep that in mind as well.
As far as I’m aware, all the documentation for the FOSS libraries shipped in the SDK image is already installed in the SDK. If you know of something which is missing, please say.
Philip
-----Original Message----- From: Devel [mailto:devel-bounces@lists.apertis.org] On Behalf Of Philip Withnall Sent: Tuesday, November 17, 2015 8:33 PM To: Barkowski Andre (CM-CI1/PRM1) Cc: devel@lists.apertis.org Subject: [Devel] Preview of new documentation tool output
Hi Andre,
I believe you were asking recently about the format of the output from the new documentation tool (hotdoc), which we’re building to replace gtk-doc.
Mathieu has produced some example output of the documentation for libgrassmoor, and I’ve attached it if you would like to take a look.
Currently, the output resembles gtk-doc’s quite faithfully — except for that it’s generated for C, Python and JavaScript bindings of the API. gtk-doc only supports C output.
For the purposes of this demo, we have not significantly changed the wording of the documentation in libgrassmoor; but we have spent some effort adding GObject Introspection annotations to it so that its APIs can be used from Python and JavaScript. These are what hotdoc uses to generate the binding documentation.
The other new feature you can see in the generated documentation is the ‘Edit’ link by each symbol. This is an early part of the implementation of an online editing system for allowing readers of the documentation to easily contribute fixes and improvements to the documentation. We believe this is a good way to encourage community contributions to the documentation by lowering the barrier to contribution.
This feature is still in development, but should be available in beta form for 15.12.
A third feature which hotdoc already has over gtk-doc is its support for incremental building, where it will only rebuild the output pages affected by the specific input files which have been changed, rather than rebuilding all output pages every time. This gives speed improvements over gtk-doc, which can take 5 minutes to build the documentation for a medium-to-large project.
Mathieu is currently working on implementing an interface for tagging symbols by their stability, private/public, supported/unsupported, and whether they are specific to an OEM (for example). We aim to have that ready for 15.12 as well. However, it does not make an appearance in the attached example.
In terms of our roadmap for after Christmas, we were thinking about the following additional features, which would be useful for Apertis and also highly desired by GNOME. If we can implement features useful to GNOME, that should increase the adoption of hotdoc there as a replacement for gtk-doc, and therefore increase its contributor base. Mathieu has spoken to various key people in the GNOME community about it (including the author of gtk-doc), and his ideas for hotdoc are well received.
• Support for stand-alone Ducktype pages (rather than just Markdown pages), which would be useful for integration with prosaic developer guides (such as the GNOME developer guide, or the Apertis developer guide), to bridge the gap between API reference manuals and developer guides • Ensure linking to Mallard manuals/pages from API documentation work (another facet of the above; this allows API documentation to link to the user manuals for developer tools which are written in Mallard [which is a markup language for documentation; a more modern version of Docbook]) • Improving the Devhelp UI to improve searching, because its current search interface doesn’t return results in relevance order or support full-text search • Improving the Devhelp UI to integrate with the hotdoc online editing system to allow typos fixes to be submitted from within Devhelp • Promoting hotdoc within GNOME by applying it to some upstream modules as a test bed and to increase adoption
The first two features would be useful for integrating API documentation and developer manuals and guides, such as an SDK development guide or the Apertis developer guidelines.
The third feature would be good for use in the SDK to actually access the new documentation. Devhelp can do this already, but sub- optimally. Alternatively, it can be accessed via the web browser — Devhelp simply has some nice features like a side search bar and keyboard shortcuts.
I’d appreciate your thoughts on these features, and how you would prioritise them in the roadmap.
Philip