[Devel] Preview of new documentation tool output

Wed Nov 18 08:52:11 GMT 2015

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 at collabora.co.uk] 
> Sent: Wednesday, November 18, 2015 2:10 PM
> To: Suma Shanbhog (RBEI/ECF4); Barkowski Andre (CM-CI1/PRM1)
> Cc: devel at 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 at lists.apertis.org] On Behalf Of
> > Philip Withnall
> > Sent: Tuesday, November 17, 2015 8:33 PM
> > To: Barkowski Andre (CM-CI1/PRM1)
> > Cc: devel at 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
> > 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 213 bytes
Desc: This is a digitally signed message part
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151118/15c5d7bc/attachment.sig>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 5445 bytes
Desc: not available
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151118/15c5d7bc/attachment.bin>