zookeeper-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Tamas Penzes (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (ZOOKEEPER-925) Consider maven site generation to replace our forrest site and documentation generation
Date Thu, 27 Sep 2018 18:56:00 GMT

    [ https://issues.apache.org/jira/browse/ZOOKEEPER-925?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16630903#comment-16630903
] 

Tamas Penzes commented on ZOOKEEPER-925:
----------------------------------------

Hi All,

I have created three sub-tasks:
* ZOOKEEPER-3153 Create MarkDown files and build process for them
* ZOOKEEPER-3154 Update release process to use the MarkDown solution
* ZOOKEEPER-3155 Remove Forrest XMLs and their build process from the project

The first one is just about creating the markdown based documentation with the opportunity
of generating HTML out of it. Adding the pom.xml files only to be able to build HTML within
this step. (It is needed to be able to compare the result with the Forrest based generated
files as part of the validation.)

In the second step I want to integrate this solution into the current ANT based process and
add the needed documentation related files to the tarball we deliver. In this step I also
want to modify the documentation about how to prepare the deliverable in the future.

As last I will clean up the old solution, like source files to Forrest based documentation,
the docs directory and so on.

Since this ticket also contains migration of the website, I will have to add more sub-tasks
in the future, when I finished the first three.

> 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: Task
>          Components: documentation
>            Reporter: Patrick Hunt
>            Assignee: Tamas Penzes
>            Priority: Major
>         Attachments: CMS_w_RST.patch, 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 was sent by Atlassian JIRA
(v7.6.3#76005)

Mime
View raw message