<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<p>Hi John,</p>
<p>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):</p>
<p><a class="moz-txt-link-freetext" href="https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#getting-started-build-configuration">https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#getting-started-build-configuration</a></p>
<p>This technique is based on the following asciidoctor extension:</p>
<p><a class="moz-txt-link-freetext" href="https://github.com/spring-io/spring-asciidoctor-extensions">https://github.com/spring-io/spring-asciidoctor-extensions</a></p>
<p>Just need to figure out how to include that in our publishing
process,</p>
<p>Paul<br>
</p>
<br>
<div class="moz-cite-prefix">On 02/01/2018 04:13 PM, John Frizelle
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CAJFhnM4LOLsU0+WDOSWkwd8Q12e12J7w95f+zdr4xnXF0TeWfQ@mail.gmail.com">
<div dir="ltr">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.
<div><br>
</div>
<div>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)...</div>
<div><br>
</div>
</div>
<div class="gmail_extra"><br clear="all">
<div>
<div class="gmail_signature" data-smartmail="gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div dir="ltr">
<div>
<div dir="ltr">
<div><font color="#999999">--</font></div>
<div>
<div style="font-size:small"><font
color="#999999">John
Frizelle</font></div>
<div style="font-size:small"><font
color="#999999">Chief
Architect, Red Hat
Mobile<br>
</font><span
style="font-family:Helvetica,Verdana,sans-serif"><font
color="#999999">Consulting
Engineer</font></span><font
color="#999999"><br>
<br>
</font>
<div><span
style="font-size:12.8000001907349px;color:rgb(153,153,153)">mobile:</span><span
style="font-size:12.8000001907349px;color:rgb(153,153,153)"> </span><span
style="font-size:12.8000001907349px;color:rgb(153,153,153)"><font
face="Tahoma, Arial,
Helvetica,
sans-serif"><b><a
href="tel://+353872901644"
target="_blank"
moz-do-not-send="true">+353 87 290 1644</a></b></font></span><br>
</div>
<div
style="font-size:12.8000001907349px"><span
style="font-family:Tahoma,Arial,Helvetica,sans-serif;color:rgb(153,153,153);font-size:12.8000001907349px">twitter:</span><b
style="font-family:Tahoma,Arial,Helvetica,sans-serif;color:rgb(153,153,153);font-size:12.8000001907349px"> @johnfriz</b><br>
</div>
<div><font color="#999999">skype: <font
face="Tahoma, Arial,
Helvetica,
sans-serif"><b>john_frizelle</b></font></font></div>
<div><span
style="color:rgb(153,153,153);font-size:12.8000001907349px">mail: </span><font
style="color:rgb(17,85,204);font-size:12.8000001907349px"
color="#999999"><b><a
href="mailto:jfrizell@redhat.com"
style="color:rgb(17,85,204);font-size:12.8000001907349px"
target="_blank"
moz-do-not-send="true">jfrizell@redhat.com</a></b></font></div>
<div><font
style="color:rgb(17,85,204);font-size:12.8000001907349px"
color="#999999"><br>
</font></div>
<div><br>
</div>
<div><img
src="cid:part3.E8858FBB.EAD90E4F@redhat.com"
class=""><font
style="color:rgb(17,85,204);font-size:12.8000001907349px"
color="#999999"><br>
</font></div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<br>
<div class="gmail_quote">On 1 February 2018 at 15:55, Wojciech
Trocki <span dir="ltr"><<a
href="mailto:wtrocki@redhat.com" target="_blank"
moz-do-not-send="true">wtrocki@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">Worth to mention that there is also
alternative aproach when all apis are available together. <br>
For example:
<div><br>
<div><a href="https://github.com/lord/slate"
target="_blank" moz-do-not-send="true">https://github.com/lord/slate</a><br>
</div>
</div>
</div>
<div>
<div class="h5">
<div class="gmail_extra"><br>
<div class="gmail_quote">On Thu, Feb 1, 2018 at 3:44
PM, Wojciech Trocki <span dir="ltr"><<a
href="mailto:wtrocki@redhat.com" target="_blank"
moz-do-not-send="true">wtrocki@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">Awesome idea to use different
tooling.
<div><br>
We could generate documentation on release (by
tooling) and use state of the art solutions
for each platform.</div>
<div>Each platform is different and there are
different tools available so keeping the
format may be hard.<br>
</div>
<div><br>
</div>
<div>There are plenty of projects that give us
this out of the box. Just couple examples:</div>
<div><br>
</div>
<div><a href="https://github.com/realm/jazzy"
target="_blank" moz-do-not-send="true">https://github.com/realm/jazzy</a>
(ios)<br>
</div>
<div><a href="http://typedoc.org/"
target="_blank" moz-do-not-send="true">http://typedoc.org/</a>
(TypeScript - cordova)<br>
</div>
<div><br>
</div>
<div>Another really good idea mentioned above is
to avoid extensive code examples in
documentation by referencing api docs.</div>
<div>We have done that in RainCatcher and it
worked really good</div>
<div><br>
</div>
<div><a
href="http://raincatcher.feedhenry.io/docs/#_logging"
target="_blank" moz-do-not-send="true">http://raincatcher.feedhenry.i<wbr>o/docs/#_logging</a>
(see logger api documentation)<br>
</div>
<div><br>
</div>
<div>This will help us to avoid our
documentation getting out of sync with the
actual code. </div>
<div>We could host that on github pages for
community.</div>
<div>I think that it will be hard to get into
details on mailing list so we could create
proposal for API docs.</div>
<div class="gmail_extra">
<div>
<div class="m_-5694976831108452802h5"><br>
<div class="gmail_quote">On Thu, Feb 1,
2018 at 3:32 PM, Paul Wright <span
dir="ltr"><<a
href="mailto:pwright@redhat.com"
target="_blank"
moz-do-not-send="true">pwright@redhat.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote"
style="margin:0 0 0
.8ex;border-left:1px #ccc
solid;padding-left:1ex">
<div text="#000000" bgcolor="#FFFFFF">
<p>Hi,</p>
<p>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).
<br>
</p>
<p>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.<br>
</p>
<p>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 <br>
</p>
<pre class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115programlisting m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115language-java" style="box-sizing:border-box;overflow:auto;font-family:Consolas,Monaco,"Andale Mono",monospace;font-size:13px;display:block;padding:0.9375rem;margin:0px 0px 1.8em;line-height:1.5;word-break:normal;word-wrap:normal;color:rgb(240,240,240);background:rgb(37,37,37);border:1px solid rgb(26,26,26);border-radius:0px;white-space:pre!important;direction:ltr;text-align:left;word-spacing:0px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;text-decoration-style:initial;text-decoration-color:initial"><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none">getSyncClient</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">(</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">)</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">.</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none">list</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">(</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115string" style="box-sizing:border-box;color:rgb(150,203,228);padding-left:0px;background:none">"tasks"</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">)</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">;</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none"></span></pre>
<p>For more information see <link
to android ref docs></p>
<pre class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115programlisting m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115language-swift" style="box-sizing:border-box;overflow:auto;font-family:Consolas,Monaco,"Andale Mono",monospace;font-size:13px;display:block;padding:0.9375rem;margin:0px 0px 1.8em;line-height:1.5;word-break:normal;word-wrap:normal;color:rgb(240,240,240);background:rgb(37,37,37);border:1px solid rgb(26,26,26);border-radius:0px;white-space:pre!important;direction:ltr;text-align:left;word-spacing:0px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;text-decoration-style:initial;text-decoration-color:initial">syncClient<span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">.</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none">listWithDataId</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">("tas<wbr>ks"</span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115constant" style="box-sizing:border-box;color:rgb(220,103,94);padding-left:0px;background:none"></span><span class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115token m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">)
</span></pre>
For more information see <link to
ios ref docs><br>
<br>
<br>
WDYT?<span
class="m_-5694976831108452802m_8786828289819325m_196875409478135777HOEnZb"><font
color="#888888"><br>
<pre class="m_-5694976831108452802m_8786828289819325m_196875409478135777m_-3618962948987576115moz-signature" cols="72">--
Paul Wright
Mobile Docs (github: finp)</pre>
</font></span></div>
<span
class="m_-5694976831108452802m_8786828289819325m_196875409478135777HOEnZb"><font
color="#888888">
-- <br>
You received this message because
you are subscribed to the Google
Groups "Aerogear" group.<br>
To unsubscribe from this group and
stop receiving emails from it,
send an email to <a
href="mailto:aerogear+unsubscribe@googlegroups.com"
target="_blank"
moz-do-not-send="true">aerogear+unsubscribe@googlegro<wbr>ups.com</a>.<br>
To post to this group, send email
to <a
href="mailto:aerogear@googlegroups.com"
target="_blank"
moz-do-not-send="true">aerogear@googlegroups.com</a>.<br>
To view this discussion on the web
visit <a
href="https://groups.google.com/d/msgid/aerogear/5749d108-985c-250a-422c-27fbaa7c3e91%40redhat.com?utm_medium=email&utm_source=footer"
target="_blank"
moz-do-not-send="true">https://groups.google.com/d/ms<wbr>gid/aerogear/5749d108-985c-250<wbr>a-422c-27fbaa7c3e91%40redhat.c<wbr>om</a>.<br>
For more options, visit <a
href="https://groups.google.com/d/optout"
target="_blank"
moz-do-not-send="true">https://groups.google.com/d/op<wbr>tout</a>.<br>
</font></span></blockquote>
</div>
<br>
<br clear="all">
<div><br>
</div>
</div>
</div>
<span class="m_-5694976831108452802HOEnZb"><font
color="#888888">-- <br>
<div
class="m_-5694976831108452802m_8786828289819325m_196875409478135777gmail_signature"
data-smartmail="gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div dir="ltr">
<div dir="ltr">
<div dir="ltr">
<div dir="ltr">
<div
style="font-size:12.8px">
<p
style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-weight:bold;margin:0px;padding:0px;font-size:14px;text-transform:uppercase"><span>WOJCIECH</span> <span>TROCKI</span></p>
<p
style="font-family:overpass,sans-serif;margin:0px;font-size:10px;color:rgb(153,153,153)"><a
href="https://www.redhat.com/"
style="color:rgb(0,136,206);margin:0px;text-decoration:none"
target="_blank"
moz-do-not-send="true">Red
Hat <span>Mobile</span></a></p>
<p
style="font-family:overpass,sans-serif;margin:0px
0px
6px;font-size:10px;color:rgb(153,153,153)"><span>IM: <span>wtrocki</span></span></p>
<table
style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"
border="0">
<tbody>
<tr>
<td width="100px"><a
href="https://red.ht/sig" target="_blank" moz-do-not-send="true"><img
src="https://www.redhat.com/files/brand/email/sig-redhat.png"
moz-do-not-send="true" height="auto" width="90"></a></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</font></span></div>
</div>
</blockquote>
</div>
<br>
<br clear="all">
<div><br>
</div>
-- <br>
<div class="m_-5694976831108452802gmail_signature"
data-smartmail="gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div dir="ltr">
<div dir="ltr">
<div dir="ltr">
<div dir="ltr">
<div style="font-size:12.8px">
<p
style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-weight:bold;margin:0px;padding:0px;font-size:14px;text-transform:uppercase"><span>WOJCIECH</span> <span>TROCKI</span></p>
<p
style="font-family:overpass,sans-serif;margin:0px;font-size:10px;color:rgb(153,153,153)"><a
href="https://www.redhat.com/"
style="color:rgb(0,136,206);margin:0px;text-decoration:none"
target="_blank"
moz-do-not-send="true">Red Hat <span>Mobile</span></a></p>
<p
style="font-family:overpass,sans-serif;margin:0px
0px
6px;font-size:10px;color:rgb(153,153,153)"><span>IM: <span>wtrocki</span></span></p>
<table
style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"
border="0">
<tbody>
<tr>
<td width="100px"><a
href="https://red.ht/sig"
target="_blank"
moz-do-not-send="true"><img
src="https://www.redhat.com/files/brand/email/sig-redhat.png"
moz-do-not-send="true"
height="auto" width="90"></a></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
-- <br>
You received this message because you are subscribed to
the Google Groups "Aerogear" group.<br>
To unsubscribe from this group and stop receiving emails
from it, send an email to <a
href="mailto:aerogear+unsubscribe@googlegroups.com"
target="_blank" moz-do-not-send="true">aerogear+unsubscribe@<wbr>googlegroups.com</a>.<br>
To post to this group, send email to <a
href="mailto:aerogear@googlegroups.com"
target="_blank" moz-do-not-send="true">aerogear@googlegroups.com</a>.<br>
</div>
</div>
To view this discussion on the web visit <a
href="https://groups.google.com/d/msgid/aerogear/CAO0%2Bn%2BqgokrQtTqd6B1Oab-upe-C5PUvJh0evyJG9Z_LPd1ArQ%40mail.gmail.com?utm_medium=email&utm_source=footer"
target="_blank" moz-do-not-send="true">https://groups.google.com/d/<wbr>msgid/aerogear/CAO0%2Bn%<wbr>2BqgokrQtTqd6B1Oab-upe-<wbr>C5PUvJh0evyJG9Z_LPd1ArQ%<wbr>40mail.gmail.com</a>.
<div class="HOEnZb">
<div class="h5"><br>
For more options, visit <a
href="https://groups.google.com/d/optout"
target="_blank" moz-do-not-send="true">https://groups.google.com/d/<wbr>optout</a>.<br>
</div>
</div>
</blockquote>
</div>
<br>
</div>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Paul Wright
Mobile Docs (github: finp)</pre>
</body>
</html>