Re: [Hawkular-dev] Documentation writing

> Am 19.02.2015 um 21:50 schrieb Catherine Robson <crobson(a)redhat.com > <mailto:crobson@redhat.com>>: > > 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: > > - Bring documentation into the Hawkular community website to > describe certain capabilties Actually this poll is about community web site - user and developer documentation. > - Bring documentation into the web console as context sensitive > help pop-ups/sidebars Yes, that can be done in at least two ways: - reference the AsciiDoc content and render it locally into e.g. html - have the community site be rendered into html and reference and just display it locally > My current understanding of Asciidoc tells me this would be possible > - but wanted to ask! Asciidoc is first and foremost a markup schema that is very human readable without additional processing tools. For example this is a part of the rest-api documentation (generated from Swagger+Jax-RS annotations on the code) -----------------------------snip-------------------------- = Rest-Api for Hawkular-Inventory == Rest api for Hawkular Inventory Implemented in: org.hawkular.inventory.rest.RestApi Produces: * application/json === GET // [.lead] Description: Just returns a string to verify reachability Return type: org.hawkular.inventory.rest.StringWrapper === POST //{tenantId}/resources [.lead] Description: Add a new resource for the passed tenantId Return type: javax.ws.rs.core.Response .Parameters |=== |Name|Required|Type|Allowed Values|Default Value|Description |tenantId|true|PATH|all||Id of the tenant ||true|BODY|all||The Resource to add |=== -----------------------------snip-------------------------- And like in html, anchors can be built in and referenced later. For e.g. http://hawkular.github.io/community/join.html the source code is here: https://raw.githubusercontent.com/hawkular/hawkular.github.io/pages/src/m... Hope that helps Heiko > > - Catherine > > >> Heiko W.RuppFebruary 19, 2015 at 4:51 AM >> Hey, >> >> please add yourself to the Doodle at http://doodle.com/a8ctk6wgwi3nh9f8 >> I will close that tomorrow SOB >> >> Heiko >> >> >> >> Heiko W.RuppFebruary 17, 2015 at 9:15 AM >> Hey, >> >> 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. >> >> I am very much in favor of using AsciiDoc + git for the documentation >> -- user and developer >> >> Clear advantages that I see for this solution: >> >> - versioning is easy as it is built into git. We can easily >> create branches for various versions of the Hawkular >> without the complicated clone process that we had in the past >> - offline possibility an author does not need to be online to write docs >> - 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 >> - Contributing is easy. People just git clone the repo, make their >> changes and submit a pull-request >> - docs are directly rendered on GitHub >> - AsciiDoc is already used in our README.adoc files >> - With AsciiDoctor there is a good tool chain for creating good >> print, html, pdf, docbook output >> - it is possible to write docs in vi/emacs/Notepad >> >> Tooling may not yet be that perfect; the mvn jbake:inline mode is >> already quite well able to re-create >> the website locally though; with a browser extension like >> "live-reload", editing a text is as wysiwyg as on a wiki >> >> >> There are other JBoss projects that follow the AsciiDoc+git approach >> with great success >> like http://arquillian.org, http://hibernate.org, http://liveoak.io, http://torquebox.org(*) >> >> Anyway I've started a doodle to get feedback and then proceed further >> - so please visit >> http://doodle.com/a8ctk6wgwi3nh9f8 >> so that we can come to a documentation solution that we all use. >> >> Heiko >> >> *) Actually uses Markdown as markup language >> >> >> >> _______________________________________________ >> hawkular-dev mailing list >> hawkular-dev(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/hawkular-dev > > -- > Catherine Robson > User Experience Design > Red Hat JBoss Middleware > c: 978-944-3825 > -- Reg. Adresse: Red Hat GmbH, Technopark II, Haus C, Werner-von-Siemens-Ring 14, D-85630 Grasbrunn Handelsregister: Amtsgericht München HRB 153243 Geschäftsführer: Charles Cachera, Michael Cunningham, Paul Hickey, Charlie Peters _______________________________________________ hawkular-dev mailing list hawkular-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hawkular-dev