[
https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930188#action_12930188
]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
There are a few issues:
A while back I looked at replacing forrest with python's sphinx, the conversion
itself was pretty straightforward given there was a script that did most of the
work. I don't see a script for forrest->confluence, perhaps we could re-purpose
the other one I used, or just do a manual search/replace of the tags. It will
take some work to convert the formats, but not huge given the size of our
forrest based docs.
Another issue was that we lost the hadoop look&feel. This was really the
insurmountable problem when I looked at it before. However now that we are
moving out of hadoop into our own tlp space I don't see that as an issue.
Probably we want our own look/feel anyway.
Going to maven based site gen we just need to create the toplevel pom.xml file
and a toplevel "src/site" directory that contains the content and the
descriptor (how to generate the site, what links, etc... that's all
configurable). We can then tell people to use both ant and mvn for the time
being. mvn would initially just be "mvn site" (site/doc generation) and ant for
all the things we do today.
I can create a patch that does maven site generation if there's sufficient
interest (I don't want to waste my time though if everyone's not on board).
What do you think?
> Consider maven site generation to replace our forrest site and documentation
> generation
> ---------------------------------------------------------------------------------------
>
> Key: ZOOKEEPER-925
> URL: https://issues.apache.org/jira/browse/ZOOKEEPER-925
> Project: Zookeeper
> Issue Type: Wish
> Components: documentation
> Reporter: Patrick Hunt
>
> See WHIRR-19 for some background.
> In whirr we looked at a number of site/doc generation facilities. In the end
> Maven site generation plugin turned out to be by far the best option. You can
> see our nascent site here (no attempt at styling,etc so far):
> http://incubator.apache.org/whirr/
> In particular take a look at the quick start:
> http://incubator.apache.org/whirr/quick-start-guide.html
> which was generated from
> http://svn.apache.org/repos/asf/incubator/whirr/trunk/src/site/confluence/quick-start-guide.confluence
> notice this was standard wiki markup (confluence wiki markup, same as
> available from apache)
> You can read more about mvn site plugin here:
> http://maven.apache.org/guides/mini/guide-site.html
> Notice that other formats are available, not just confluence markup, also
> note that you can use different markup formats if you like in the same site
> (although probably not a great idea, but in some cases might be handy, for
> example whirr uses the confluence wiki, so we can pretty much copy/paste
> source docs from wiki to our site (svn) if we like)
> Re maven vs our current ant based build. It's probably a good idea for us to
> move the build to maven at some point. We could initially move just the doc
> generation, and then incrementally move functionality from build.xml to mvn
> over a longer time period.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
