You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@zookeeper.apache.org by "Patrick Hunt (JIRA)" <ji...@apache.org> on 2010/11/09 02:54:10 UTC
[jira] Created: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
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)
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Flavio Junqueira (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12929988#action_12929988 ]
Flavio Junqueira commented on ZOOKEEPER-925:
--------------------------------------------
Pat, Any thoughts on how it would be to port from Forrest to Maven site generation?
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Benjamin Reed (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930205#action_12930205 ]
Benjamin Reed commented on ZOOKEEPER-925:
-----------------------------------------
i'm totally interested in moving to maven site! i really really want to get away from forrest and make it a bit easier to write doc. can we also get away from checking in generated doc?
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Alex Baranau (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12932926#action_12932926 ]
Alex Baranau commented on ZOOKEEPER-925:
----------------------------------------
Hello guys,
It looks like the process of switching to maven site generation is in it's origin, but still want to ask about whether there will be site template file (site.vm) added (to make things more flexible, etc.)? I'm asking because I'm looking into adding integration with search service we used (search-hadoop.com).
Fwiw, for HBase we started use site.vm with adding search service integration (HBASE-2886). Guys liked the place/style it was integrated in there. You can check out this link: http://hbase.apache.org/docs/r0.89.20100924/ to see how it looks.
Thanks!
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Alex Baranau (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12933036#action_12933036 ]
Alex Baranau commented on ZOOKEEPER-925:
----------------------------------------
It can be specified in pom.xml for maven-site-plugin via templateFile property.
If it's OK, I can adjust current patch to include this, so that from this point it includes (and uses) template in it.
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Benjamin Reed (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12933072#action_12933072 ]
Benjamin Reed commented on ZOOKEEPER-925:
-----------------------------------------
yeah i tried doxia converter with various different formats and strategies.
the problem with db2rst is, even if i get it to rst, how do i get it to confluence?
i looked at the search/replace, but it turns out that we do use quite a bit of tags that are a bit complicated, so there isn't an easy way to do it. perhaps it would be easy with xsl, but i don't know xsl.
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12934978#action_12934978 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
See this for more background on CMS: http://www.apache.org/dev/infra-site.html
> 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.
[jira] Updated: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930226#action_12930226 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
btw, given you just checkout the repo and literally type "mvn site" (maven handles all the dependency d/l) there's basically no reason to commit the generated docs.
> 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.
[jira] Updated: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ 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
apply this patch, then in the toplevel directory type "mvn site:site", then open target/site/index.html in your browser.
Notice the index.confluence src page, try editing that (confluence wiki markup http://maven.apache.org/doxia/modules/index.html#Confluence) and regenerating/viewing the updated site. site.xml controls the layout and which links are put into the generated site.
> 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
> Attachments: 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930224#action_12930224 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
We prolly wouldn't generate pdfs for the web site, no one seems to do that anymore (although it's possible if someone would want to do it explicitly for some reason)
We check in the source, that's a given.
We check in the generated site/docs for a reason as well. In forrest timeframe it was mainly due to the fact that using forrest is a pita. ;-) In maven that's less of a concern. For whirr we currently don't checkin the generated, but we are thinking of doing so to lower the bar for new users. Doesn't really matter much to me, we could try "not committing generated" first, then see if it's an issue.
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Benjamin Reed (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930517#action_12930517 ]
Benjamin Reed commented on ZOOKEEPER-925:
-----------------------------------------
this is pretty cool! we can generate pdfs by using doxia converter to go from confluence to latex.
> 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
>
>
> 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.
[jira] Updated: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Patrick Hunt updated ZOOKEEPER-925:
-----------------------------------
Description:
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.
was:
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)
> 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.
[jira] Assigned: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Patrick Hunt reassigned ZOOKEEPER-925:
--------------------------------------
Assignee: Patrick Hunt
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Benjamin Reed (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12932592#action_12932592 ]
Benjamin Reed commented on ZOOKEEPER-925:
-----------------------------------------
+1 for confluence
it would be great to target 1) for when we move to tlp.
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Flavio Junqueira (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930214#action_12930214 ]
Flavio Junqueira commented on ZOOKEEPER-925:
--------------------------------------------
I was wondering if by getting away from checking in generated docs, you mean that anyone should be able to come and change docs freely.
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930204#action_12930204 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
Agree. mvn site is an order of mag better than forrest. For one you don't need to have java5 and the perf is alot better (although it's early days yet, afaict it's better). Also wiki markup is "easier", but in general I haven't had that much of an issue with forrest markup once I started using nxml in emacs.
+1 (good if it's more than just flavio) this if you want me to take a stab.
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12932590#action_12932590 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
At this point to move fwd we need to work on 2 main areas:
1) site gen
2) doc conversion
item 1) is looking pretty good, but some work yet to be done, icons and look/feel mainly
item 2) just requires us to decide which if any format we want to standardize on and then try moving some docs to that format.
I would highly suggest that our "standard/preferred" format be confluence format -- we can move our wiki to there at some point, which will match up nicely.
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12933018#action_12933018 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
@Alex looks good to me. We're new with mvn based site gen, what's the implications on our side of adding a site.vm file? Is that not something we can specify with site.xml?
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12933074#action_12933074 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
TANSTAAFL ;-) You'd have to modify the db2rst a bit to get it to output confluence tags, iirc that was pretty easy to do (plus it's in python). Or find a rst to confluence converter (I looked a bit last night but didn't find, would doxia converter work?)
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Thomas Koch (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930547#action_12930547 ]
Thomas Koch commented on ZOOKEEPER-925:
---------------------------------------
Please don't check in _any_ generated files in version control. When I package zookeeper for Debian (same applies to any other free software distro) I may not include generated files.
Debian needs to make sure that it has all source files for everything that's delivered and that it attributes the copyright correctly. Not having any generated files but to generate everything at Debian package build time makes this a lot easier.
Just a note: The same applies for the released tarballs, but that's another topic.
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Benjamin Reed (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930526#action_12930526 ]
Benjamin Reed commented on ZOOKEEPER-925:
-----------------------------------------
since maven generates the doc without requiring preinstalled tools. i don't think it is onerous at all to just check in the sources and require users to compile the doc if they are using trunk.
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Flavio Junqueira (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930201#action_12930201 ]
Flavio Junqueira commented on ZOOKEEPER-925:
--------------------------------------------
I'm fine with moving to a different doc system and having our own look&feel, but my main concern is having a doc generation that is relatively easy to use. If it is difficult to use, then contributors won't feel very motivated to write documentation... It would be great to get folks to stop whining when they have to write documentation, and stop blaming Forrest. :-)
To be fair, I must say that my experience with Forrest hasn't been great. Having to insert tags by hand and not being able to find descriptions for tags easily made it hard for me to like Forrest. The output looks good for me, though.
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12932847#action_12932847 ]
Patrick Hunt commented on ZOOKEEPER-925:
----------------------------------------
Ben did you try this tool I pointed you to previously?
http://code.google.com/p/db2rst/
I used it to try converting to sphinx (rst), you should be able to use it to convert to confluence markup with some changes.
Did you try the doxia converter?
Perhaps some search/replace will get alot of it? We don't use that many tags...
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Benjamin Reed (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12932799#action_12932799 ]
Benjamin Reed commented on ZOOKEEPER-925:
-----------------------------------------
i cannot figure out how to convert forrest to anything. actually, i can't figure out how we have forrest working at all! after burning the afternoon trying to figure out how to convert forrest to confluence, i'm officially declaring defeat. it should be an easy thing to do for an xml/xsl master, but that is not me.
the most promising thing appears to be the doxia converter that will go from a bunch of formats to a bunch more formats, including from docbook or xdoc to confluence. unfortunately, forrest seems close to both of those, but not close enough...
> 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
>
>
> 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Patrick Hunt (JIRA)" <ji...@apache.org>.
[ 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.
[jira] Commented: (ZOOKEEPER-925) Consider maven site generation to
replace our forrest site and documentation generation
Posted by "Benjamin Reed (JIRA)" <ji...@apache.org>.
[ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12930221#action_12930221 ]
Benjamin Reed commented on ZOOKEEPER-925:
-----------------------------------------
just to be clear. we should check in the source for the docs. i'm just saying that we check only check in the source for the docs, not the generated pdfs and web pages.
> 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.