3:47 a.m.
Hello Guys,
To keep your documentation DRY, Karel suggested the usage of acsciidoc
include in this ML thread [1].
We tried with Erik* some experiment, it's in this gist [2].
I think it's aneat feature and we could use it in different way:
1) reuse some cookbook documentation page (if in asciidoc format)
2) embed source code snippet in our documentation to make sure our doc is
always up to date with latest code
Just wanted to check with you if you like the idea bacause it will involve
some documentation format changes (part of your web site revamp). Note: we
could use code snippet include (option2) without option 1).
wdyt?
++
Corinne
[1]
http://aerogear-dev.1069024.n5.nabble.com/aerogear-dev-Fwd-Website-restru...
[2] https://gist.github.com/anonymous/dac8efdb7c90206acffe
*asciisoc hero
3:58 a.m.
I think it’s a great idea having the same examples and code fragments all over the place
is a bad thing. This way our documentation code snippets are guaranteed to compile and
execute and can even be refactored!
5:26 a.m.
One other improvement I was thinking of was to setup a git commit hook.
The idea is that asciidoc reference snippets by file+line#
This hook will basically do following:
1/ Check files for asciidoc annotatations in the repository - e.g.
// @asciidoc-example-start
public void mySuperPipeExampleThatGoesToPipeDoc(Pipe p) {
p.ftw();
}
// @asciidoc-example-end
2/ Apply commit
3/ Check once again if the line numbers of asciidoc annotations is the same
4/ If not, produce a *FAT* warning that commiter should update
aerogear.github.com repo with new line numbers to align doc.
This should keep code and doc up-to-date.
I can create such hook, the question is what is "the most usual env"(tm)
so it would be working for everybody - assuming sh/awk/grep will do?
Karel
On Thu, 13 Feb 2014 10:58:17 +0100
Erik Jan de Wit <edewit(a)redhat.com> wrote:
I think it’s a great idea having the same examples and code fragments
all
over the place is a bad thing. This way our documentation code snippets are
guaranteed to compile and execute and can even be refactored!
_______________________________________________ aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
5:57 a.m.
Like it, that way it will not get misaligned by accident
On 13 Feb,2014, at 12:26 , Karel Piwko <kpiwko(a)redhat.com> wrote:
One other improvement I was thinking of was to setup a git commit
hook.
The idea is that asciidoc reference snippets by file+line#
This hook will basically do following:
1/ Check files for asciidoc annotatations in the repository - e.g.
// @asciidoc-example-start
public void mySuperPipeExampleThatGoesToPipeDoc(Pipe p) {
p.ftw();
}
// @asciidoc-example-end
2/ Apply commit
3/ Check once again if the line numbers of asciidoc annotations is the same
4/ If not, produce a *FAT* warning that commiter should update
aerogear.github.com repo with new line numbers to align doc.
This should keep code and doc up-to-date.
I can create such hook, the question is what is "the most usual env"(tm)
so it would be working for everybody - assuming sh/awk/grep will do?
Karel
On Thu, 13 Feb 2014 10:58:17 +0100
Erik Jan de Wit <edewit(a)redhat.com> wrote:
> I think it’s a great idea having the same examples and code fragments all
> over the place is a bad thing. This way our documentation code snippets are
> guaranteed to compile and execute and can even be refactored!
> _______________________________________________ aerogear-dev mailing list
> aerogear-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
3965
days inactive
3965
days old
3 comments
3 participants
participants (3)
-
Corinne Krych -
Erik Jan de Wit -
Karel Piwko