[
https://issues.apache.org/jira/browse/WHIRR-19?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12877124#action_12877124
]
Tom White commented on WHIRR-19:
--------------------------------
> From the asciidoc web site if I understand correctly asciidoc can generate
> not only single page documents, but also "website" as well. Is that right?
> (multiple documents with navigation btw them?)
You can do this, but it involves transforming Asciidoc into DocBook first to
generate a multi-page document/site. This is quite a complex toolchain (which
is why you need so many packages), so I would prefer something simpler.
> Or should we not have the generated docs in trunk? (I find it useful for ppl
> checking out the source, but it does add additional small burden to commiter).
It is useful, but I think the reason we stopped doing this in Hadoop was
because of the extra burden to generate Forrest docs. If the burden is small
then I think we should check in the generated docs (this is why asciidoc is
probably not a good choice).
I spent a bit more time looking at other Apache sites, and quite a few do use
exported confluence to good effect (e.g. Camel, Jackrabbit, Sling, Wicket), but
the limitation, as noted above, is that only people who have signed an ICLA can
edit documentation. This sounds like a barrier to me, but perhaps I'm over
optimistic about how much documentation is contributed? It's possible for
anyone to add comments to a page though.
So I'm tending to think we should take the Cassandra route - have a minimal
website (one page?) as a jumping off point, with versioned release
documentation in javadoc (with top-level docs in the overview file - there
would be one for core and one per service - or even extra plain HTML files, see
http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/javadoc.html#unprocessed),
and a link to the wiki for further information. We could introduce a different
documentation system at a later point if we wanted more structured
documentation outside javadoc. This could be another confluence wiki, or sphinx
(which looks easy to install, and the markup is reasonable), or something else
(\!).
Sound good?
> Create project website
> ----------------------
>
> Key: WHIRR-19
> URL: https://issues.apache.org/jira/browse/WHIRR-19
> Project: Whirr
> Issue Type: Task
> Components: documentation
> Reporter: Tom White
> Priority: Blocker
> Fix For: 0.1.0
>
>
> Whirr needs a website at http://incubator.apache.org/whirr.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
