[
https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Patrick Hunt updated ZOOKEEPER-925:
-----------------------------------
Attachment: ZOOKEEPER-925.patch
This updated patch has a db2confluence.py script which attempts to convert our
docs from simpledocbook to confluence format. I converted the admin guide as an
example.
Try running "mvn site" then open the generated html file for admin (in target
directory)
Note:
1) doxia confluence doesn't support toc generation, so we'd need to maintain
this for the time being until they implement
2) the "note" sections are not supported. We'd have to reformat this a bit
ourselves to make it work (probably by specifying a css class that provides
similar style)
3) xrefs in sdocbook will pull in the text of the referenced section, the
conversion tool does not do this. We'd have to add this as part of the
conversion.
Take a look ant let me know. Anyone could run the conversion on the other docs
to see how it works there (I only ran on admin). Use db2confluence.py (redirect
stdout) to test on the other files.
The python script (included in patch) is pretty simple to tweak if we notice
other elements that are not being converted (correctly).
> 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
> Assignee: Patrick Hunt
> Attachments: ZOOKEEPER-925.patch, ZOOKEEPER-925.patch
>
>
> 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.
