[aerogear-dev] SDK API doc
Paul Wright
pwright at redhat.com
Sun Feb 4 08:52:23 EST 2018
Hi John,
Given that we want to document in asciidoc, I'm suggesting that we
(somehow) use the same technique as used here to display alternative
syntax (maven and gradle tabs):
https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#getting-started-build-configuration
This technique is based on the following asciidoctor extension:
https://github.com/spring-io/spring-asciidoctor-extensions
Just need to figure out how to include that in our publishing process,
Paul
On 02/01/2018 04:13 PM, John Frizelle wrote:
> I think some beautiful marriage between stand alone API docs for the
> deep documentation and slate for language specific samples examples is
> the way to go here.
>
> I actually really like the slate UI & UX and would be very much in
> favour of using it (at least at some layer of our docs)...
>
>
> --
> John Frizelle
> Chief Architect, Red Hat Mobile
> Consulting Engineer
>
> mobile:*+353 87 290 1644 <tel://+353872901644>*
> twitter:* @johnfriz*
> skype: *john_frizelle*
> mail: *jfrizell at redhat.com <mailto:jfrizell at redhat.com>*
>
>
>
>
> On 1 February 2018 at 15:55, Wojciech Trocki <wtrocki at redhat.com
> <mailto:wtrocki at redhat.com>> wrote:
>
> Worth to mention that there is also alternative aproach when all
> apis are available together.
> For example:
>
> https://github.com/lord/slate
>
> On Thu, Feb 1, 2018 at 3:44 PM, Wojciech Trocki
> <wtrocki at redhat.com <mailto:wtrocki at redhat.com>> wrote:
>
> Awesome idea to use different tooling.
>
> We could generate documentation on release (by tooling) and
> use state of the art solutions for each platform.
> Each platform is different and there are different tools
> available so keeping the format may be hard.
>
> There are plenty of projects that give us this out of the box.
> Just couple examples:
>
> https://github.com/realm/jazzy (ios)
> http://typedoc.org/ (TypeScript - cordova)
>
> Another really good idea mentioned above is to avoid extensive
> code examples in documentation by referencing api docs.
> We have done that in RainCatcher and it worked really good
>
> http://raincatcher.feedhenry.io/docs/#_logging
> <http://raincatcher.feedhenry.io/docs/#_logging> (see logger
> api documentation)
>
> This will help us to avoid our documentation getting out of
> sync with the actual code.
> We could host that on github pages for community.
> I think that it will be hard to get into details on mailing
> list so we could create proposal for API docs.
>
> On Thu, Feb 1, 2018 at 3:32 PM, Paul Wright
> <pwright at redhat.com <mailto:pwright at redhat.com>> wrote:
>
> Hi,
>
> There is existing tooling to generate API reference doc
> for Android and iOS. I'm thinking we should use that to
> generate comprehensive API doc for both platforms (and
> later for Cordova).
>
> I believe this gives the best experience to the <platform>
> developer, on the basis that, at any one time, they
> developer is working on a single platform (and typically a
> colleague is developing the 'other' platform). The
> disadvantages of this approach include the fact that the
> appearance of generic docs/android/ios will all be
> different, but we can put enough navigation into the html
> to allow users enter and exit this reference without too
> much pain.
>
> However there is also a requirement to show the cross
> platform nature of mobile-next, to demonstrate the generic
> nature of a particular call. I'd like to address this, not
> in the 'full' API docs, but in examples of typical use
> cases which might look like
>
> getSyncClient().list("tasks");
>
> For more information see <link to android ref docs>
>
> syncClient.listWithDataId("tasks")
>
> For more information see <link to ios ref docs>
>
>
> WDYT?
>
> --
> Paul Wright
> Mobile Docs (github: finp)
>
> --
> You received this message because you are subscribed to
> the Google Groups "Aerogear" group.
> To unsubscribe from this group and stop receiving emails
> from it, send an email to
> aerogear+unsubscribe at googlegroups.com
> <mailto:aerogear+unsubscribe at googlegroups.com>.
> To post to this group, send email to
> aerogear at googlegroups.com <mailto:aerogear at googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/aerogear/5749d108-985c-250a-422c-27fbaa7c3e91%40redhat.com
> <https://groups.google.com/d/msgid/aerogear/5749d108-985c-250a-422c-27fbaa7c3e91%40redhat.com?utm_medium=email&utm_source=footer>.
> For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
>
>
>
>
> --
>
> WOJCIECH TROCKI
>
> Red Hat Mobile <https://www.redhat.com/>
>
> IM: wtrocki
>
> <https://red.ht/sig>
>
>
>
>
> --
>
> WOJCIECH TROCKI
>
> Red Hat Mobile <https://www.redhat.com/>
>
> IM: wtrocki
>
> <https://red.ht/sig>
>
> --
> You received this message because you are subscribed to the Google
> Groups "Aerogear" group.
> To unsubscribe from this group and stop receiving emails from it,
> send an email to aerogear+unsubscribe at googlegroups.com
> <mailto:aerogear+unsubscribe at googlegroups.com>.
> To post to this group, send email to aerogear at googlegroups.com
> <mailto:aerogear at googlegroups.com>.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/aerogear/CAO0%2Bn%2BqgokrQtTqd6B1Oab-upe-C5PUvJh0evyJG9Z_LPd1ArQ%40mail.gmail.com
> <https://groups.google.com/d/msgid/aerogear/CAO0%2Bn%2BqgokrQtTqd6B1Oab-upe-C5PUvJh0evyJG9Z_LPd1ArQ%40mail.gmail.com?utm_medium=email&utm_source=footer>.
>
>
> For more options, visit https://groups.google.com/d/optout
> <https://groups.google.com/d/optout>.
>
>
--
Paul Wright
Mobile Docs (github: finp)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180204/9f8021d7/attachment-0001.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: logo.png
Type: image/png
Size: 11472 bytes
Desc: not available
Url : http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180204/9f8021d7/attachment-0001.png
More information about the aerogear-dev
mailing list