[Devel] Preview of new documentation tool output

Wed Nov 18 08:47:03 GMT 2015

Hi Philip,

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 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?

Best regards

Suma L
RBEI/ECF  

Tel. +91(80)6657-4464

-----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: smime.p7s
Type: application/x-pkcs7-signature
Size: 6715 bytes
Desc: not available
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151118/734a2131/attachment-0001.bin>