<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><br class=""><blockquote type="cite" class="">Am 19.02.2015 um 21:50 schrieb Catherine Robson <<a href="mailto:crobson@redhat.com" class="">crobson@redhat.com</a>>:<br class=""><br class="">Would we be able to take documentation written in Git with Asciidoc and dynamically place that into other UI outputs? Two reasons of why this might be useful:<br class=""><br class="">- Bring documentation into the Hawkular community website to describe certain capabilties<br class=""></blockquote><div class=""><br class=""></div><div class="">Actually this poll is about community web site - user and developer documentation.</div><br class=""><blockquote type="cite" class="">- Bring documentation into the web console as context sensitive help pop-ups/sidebars<br class=""></blockquote><div class=""><br class=""></div>Yes, that can be done in at least two ways:<div class="">- reference the AsciiDoc content and render it locally into e.g. html</div><div class="">- have the community site be rendered into html and reference and just display it locally</div><div class=""><br class=""><blockquote type="cite" class="">My current understanding of Asciidoc tells me this would be possible - but wanted to ask!<br class=""></blockquote><div class=""><br class=""></div>Asciidoc is first and foremost a markup schema that is very human readable without additional processing tools.</div><div class=""><br class=""></div><div class="">For example this is a part of the rest-api documentation (generated from Swagger+Jax-RS annotations on the code)</div><div class=""><br class=""></div><div class="">-----------------------------snip--------------------------</div><div class="">= Rest-Api for Hawkular-Inventory<br class=""><br class="">== Rest api for Hawkular Inventory<br class=""><br class="">Implemented in: org.hawkular.inventory.rest.RestApi<br class=""><br class="">Produces:<br class=""><br class="">* application/json<br class=""><br class="">=== GET //<br class=""><br class="">[.lead]<br class="">Description: Just returns a string to verify reachability<br class=""><br class="">Return type: org.hawkular.inventory.rest.StringWrapper<br class=""><br class=""><br class="">=== POST //{tenantId}/resources<br class=""><br class="">[.lead]<br class="">Description: Add a new resource for the passed tenantId<br class=""><br class="">Return type: javax.ws.rs.core.Response<br class=""><br class="">.Parameters<br class="">|===<br class="">|Name|Required|Type|Allowed Values|Default Value|Description<br class=""><br class="">|tenantId|true|PATH|all||Id of the tenant<br class="">||true|BODY|all||The Resource to add<br class="">|===<br class=""><br class="">-----------------------------snip--------------------------</div><div class=""><br class=""></div><div class="">And like in html, anchors can be built in and referenced later.</div><div class=""><br class=""></div><div class="">For e.g. <a href="http://hawkular.github.io/community/join.html" class="">http://hawkular.github.io/community/join.html</a></div><div class="">the source code is here: <a href="https://raw.githubusercontent.com/hawkular/hawkular.github.io/pages/src/main/jbake/content/community/join.adoc" class="">https://raw.githubusercontent.com/hawkular/hawkular.github.io/pages/src/main/jbake/content/community/join.adoc</a></div><div class=""><br class=""></div><div class="">Hope that helps</div><div class=""><br class=""></div><div class=""> Heiko</div><div class=""><br class=""></div><div class=""><br class=""><blockquote type="cite" class=""><br class=""></blockquote><div class=""><br class=""></div><div class=""><br class=""></div><br class=""><blockquote type="cite" class="">- Catherine<br class=""><br class=""><br class=""><blockquote style="border: 0px none;" cite="mid:3F689D66-6FA5-4346-ACAA-526ADA787AD5@redhat.com" type="cite" class=""><img photoaddress="hrupp@redhat.com" photoname="Heiko W.Rupp" name="compose-unknown-contact.jpg" height="25px" width="25px" class="" apple-inline="yes" id="321AEF29-D8A7-4BD9-85DD-00AA904A70B0" src="cid:part1.01000706.02060202@redhat.com"><span class="Apple-tab-span" style="white-space:pre"> </span>Heiko W.Rupp<span class="Apple-tab-span" style="white-space:pre"> </span>February 19, 2015 at 4:51 AM<br class="">Hey,<br class=""><br class="">please add yourself to the Doodle at <a href="http://doodle.com/a8ctk6wgwi3nh9f8" class="">http://doodle.com/a8ctk6wgwi3nh9f8</a> <br class="">I will close that tomorrow SOB<br class=""><br class="">Heiko<br class=""><br class=""><br class=""><br class=""><img photoaddress="hrupp@redhat.com" photoname="Heiko W.Rupp" name="compose-unknown-contact.jpg" height="25px" width="25px" class="" apple-inline="yes" id="5D3C3766-EFC1-411F-A4AB-DEFA5997EEDD" src="cid:part1.01000706.02060202@redhat.com"><span class="Apple-tab-span" style="white-space:pre"> </span>Heiko W.Rupp<span class="Apple-tab-span" style="white-space:pre"> </span>February 17, 2015 at 9:15 AM<br class="">Hey,<br class=""><br class="">as we made some progress with hawkular.github.io, the question came up what should go there and if we can't just use something else instead.<br class=""><br class="">I am very much in favor of using AsciiDoc + git for the documentation -- user and developer<br class=""><br class="">Clear advantages that I see for this solution:<br class=""><br class="">- versioning is easy as it is built into git. We can easily create branches for various versions of the Hawkular<br class="">without the complicated clone process that we had in the past<br class="">- offline possibility an author does not need to be online to write docs<br class="">- AsciiDoc is plain text. The pages may have a handful of specific header lines, but if you don't want to format any markup, then just don't<br class="">- Contributing is easy. People just git clone the repo, make their changes and submit a pull-request<br class="">- docs are directly rendered on GitHub<br class="">- AsciiDoc is already used in our README.adoc files<br class="">- With AsciiDoctor there is a good tool chain for creating good print, html, pdf, docbook output<br class="">- it is possible to write docs in vi/emacs/Notepad<br class=""><br class="">Tooling may not yet be that perfect; the mvn jbake:inline mode is already quite well able to re-create <br class="">the website locally though; with a browser extension like "live-reload", editing a text is as wysiwyg as on a wiki<br class=""><br class=""><br class="">There are other JBoss projects that follow the AsciiDoc+git approach with great success<br class="">like http://arquillian.org, http://hibernate.org, http://liveoak.io, http://torquebox.org(*)<br class=""><br class="">Anyway I've started a doodle to get feedback and then proceed further - so please visit<br class="">http://doodle.com/a8ctk6wgwi3nh9f8<br class="">so that we can come to a documentation solution that we all use.<br class=""><br class="">Heiko<br class=""><br class="">*) Actually uses Markdown as markup language<br class=""><br class=""><br class=""><br class="">_______________________________________________<br class="">hawkular-dev mailing list<br class="">hawkular-dev@lists.jboss.org<br class="">https://lists.jboss.org/mailman/listinfo/hawkular-dev<br class=""></blockquote><br class="">-- <br class="">Catherine Robson<br class="">User Experience Design<br class="">Red Hat JBoss Middleware<br class="">c: 978-944-3825<br class=""><br class=""></blockquote><br class=""><div class="">-- <br class="">Reg. Adresse: Red Hat GmbH, Technopark II, Haus C, <br class="">Werner-von-Siemens-Ring 14, D-85630 Grasbrunn<br class="">Handelsregister: Amtsgericht München HRB 153243<br class="">Geschäftsführer: Charles Cachera, Michael Cunningham, Paul Hickey, Charlie Peters<br class=""></div><br class=""></div></body></html>