Avro
  1. Avro
  2. AVRO-319

Replace Forrest for documentation generation

    Details

    • Type: Improvement Improvement
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: build
    • Labels:
      None

      Description

      Drop options in the comments and we can decide on a better system than Forrest

        Issue Links

          Activity

          Hide
          Jeff Hammerbacher added a comment -

          Sphinx is popular in the Python community: http://sphinx.pocoo.org

          Show
          Jeff Hammerbacher added a comment - Sphinx is popular in the Python community: http://sphinx.pocoo.org
          Hide
          Doug Cutting added a comment -

          There's a plugin for Forrest that generates Anakia files. This was used by the Incubator to switch from Forrest to Anakia due to frustration with Forrest.

          Anakia is another Apache, Java-based, XML-in, HTML-out system, except it's faster, easier to use, etc. than Forrest. HTTPD and APR, no-nonsense C projects, no fans of Java, use Anakia for their websites: https://svn.apache.org/repos/asf/httpd/site/trunk/.

          Show
          Doug Cutting added a comment - There's a plugin for Forrest that generates Anakia files. This was used by the Incubator to switch from Forrest to Anakia due to frustration with Forrest. Anakia is another Apache, Java-based, XML-in, HTML-out system, except it's faster, easier to use, etc. than Forrest. HTTPD and APR, no-nonsense C projects, no fans of Java, use Anakia for their websites: https://svn.apache.org/repos/asf/httpd/site/trunk/ .
          Hide
          Patrick Hunt added a comment -

          fwiw in zookeeper we've seen a few major complaints on forrest; 1) use of xml for markup, 2) the project seems very "cobbled up"
          in the sense that there's all kinds of third party libs are used that make things very difficult to debug/fix when problems occur, and 3)
          the fact that the project is not making progress (still requires java5 and no releases for > 2 yrs)

          zookeeper has been considering sphinx and possibly webby http://webby.rubyforge.org/ (python/ruby respectively)

          both of these implementations allow simpler/focused markup forms

          thoughts on xml vs "markup"? I believe sphinx uses reST while webby allows a number of diff input formats. sphinx/webby both allow
          html/pdf output. First I've heard of anakia, but it doesn't seem like a good option for us (zk) as it uses xml for input.

          Show
          Patrick Hunt added a comment - fwiw in zookeeper we've seen a few major complaints on forrest; 1) use of xml for markup, 2) the project seems very "cobbled up" in the sense that there's all kinds of third party libs are used that make things very difficult to debug/fix when problems occur, and 3) the fact that the project is not making progress (still requires java5 and no releases for > 2 yrs) zookeeper has been considering sphinx and possibly webby http://webby.rubyforge.org/ (python/ruby respectively) both of these implementations allow simpler/focused markup forms thoughts on xml vs "markup"? I believe sphinx uses reST while webby allows a number of diff input formats. sphinx/webby both allow html/pdf output. First I've heard of anakia, but it doesn't seem like a good option for us (zk) as it uses xml for input.
          Hide
          Jeff Hammerbacher added a comment -

          Making a blocker for 1.4.0. No one should have to suffer the pain that I am suffering right now trying to get Java 5 installed to build a release. Forrest is a plague upon Apache projects.

          Show
          Jeff Hammerbacher added a comment - Making a blocker for 1.4.0. No one should have to suffer the pain that I am suffering right now trying to get Java 5 installed to build a release. Forrest is a plague upon Apache projects.
          Hide
          Doug Cutting added a comment -

          I question whether this should be a blocker. Has someone volunteered to implement this? Would you really want to block a 1.4.0 release if this is not complete?

          Show
          Doug Cutting added a comment - I question whether this should be a blocker. Has someone volunteered to implement this? Would you really want to block a 1.4.0 release if this is not complete?
          Hide
          Jeff McCarrell added a comment -
          Show
          Jeff McCarrell added a comment - The Anakia project: http://velocity.apache.org/anakia/releases/anakia-1.0/
          Hide
          Jeff McCarrell added a comment -

          proposal:

          the goal is: to end the suffering of forrest

          • other possible documentation refactoring is not in scope
            follow the existing model as much as possible:
          • only change what has to change; don't make additional work
          • existing language formatters do not change
            • C++ : doxygen
            • C : asciidoc
            • java : javadoc
          • language doc generation steps are separate from the top level docs generation
            desired style will resemble httpd.apache.org
          • use anakia to build the top level site
          • but only the top level site gets generated via anakia
            PDF support is dropped as of 1.4
          • because anakia doesn't support it
            older versions of the documentation get stored as is (post rendering) in svn?
            or live on the site?
            open issue
            to build the top level site docs requires:
          • a modern jvm and ant installed
          • svn checkout trunk
          • cd xdocs && ant docs
          • source: xdocs; target: build/docs
            • anakia/velocity jar(s) checked into svn

          so that means these sets of files:

          proteus-> find site/author/content/xdocs -type f | grep -v .svn
          site/author/content/xdocs/credits.xml
          site/author/content/xdocs/index.xml
          site/author/content/xdocs/irc.xml
          site/author/content/xdocs/issue_tracking.xml
          site/author/content/xdocs/mailing_lists.xml
          site/author/content/xdocs/releases.xml
          site/author/content/xdocs/site.xml
          site/author/content/xdocs/tabs.xml
          site/author/content/xdocs/version_control.xml

          proteus-> find trunk/doc -type f | grep -v .svn
          trunk/doc/build.xml
          trunk/doc/src/content/xdocs/idl.xml
          trunk/doc/src/content/xdocs/index.xml
          trunk/doc/src/content/xdocs/site.xml
          trunk/doc/src/content/xdocs/spec.xml
          trunk/doc/src/content/xdocs/tabs.xml
          trunk/doc/src/resources/images/avro-logo.png
          trunk/doc/src/resources/images/favicon.ico
          trunk/doc/src/resources/images/hadoop-logo.jpg
          trunk/doc/src/skinconf.xml

          are changed, and pretty much nothing else is.

          Show
          Jeff McCarrell added a comment - proposal: the goal is: to end the suffering of forrest other possible documentation refactoring is not in scope follow the existing model as much as possible: only change what has to change; don't make additional work existing language formatters do not change C++ : doxygen C : asciidoc java : javadoc language doc generation steps are separate from the top level docs generation desired style will resemble httpd.apache.org use anakia to build the top level site but only the top level site gets generated via anakia PDF support is dropped as of 1.4 because anakia doesn't support it older versions of the documentation get stored as is (post rendering) in svn? or live on the site? open issue to build the top level site docs requires: a modern jvm and ant installed svn checkout trunk cd xdocs && ant docs source: xdocs; target: build/docs anakia/velocity jar(s) checked into svn so that means these sets of files: proteus-> find site/author/content/xdocs -type f | grep -v .svn site/author/content/xdocs/credits.xml site/author/content/xdocs/index.xml site/author/content/xdocs/irc.xml site/author/content/xdocs/issue_tracking.xml site/author/content/xdocs/mailing_lists.xml site/author/content/xdocs/releases.xml site/author/content/xdocs/site.xml site/author/content/xdocs/tabs.xml site/author/content/xdocs/version_control.xml proteus-> find trunk/doc -type f | grep -v .svn trunk/doc/build.xml trunk/doc/src/content/xdocs/idl.xml trunk/doc/src/content/xdocs/index.xml trunk/doc/src/content/xdocs/site.xml trunk/doc/src/content/xdocs/spec.xml trunk/doc/src/content/xdocs/tabs.xml trunk/doc/src/resources/images/avro-logo.png trunk/doc/src/resources/images/favicon.ico trunk/doc/src/resources/images/hadoop-logo.jpg trunk/doc/src/skinconf.xml are changed, and pretty much nothing else is.
          Hide
          Scott Carey added a comment -

          Thats a clean quick way to get off of Forrest.

          But yuck, Anakina makes ugly web pages. Tomcat and httpd look like the web in 1998. Any examples that actually look decent?

          We can improve the site design, look/feel/navigation any other time, for now getting rid of the Forrest mess would be a big improvement – many more people would be able to do a full build + package for testing.

          How important is pdf generation of docs? It is definitely nice for the Avro spec, but if the HTML version prints decently we may be able to get by for a while without it.

          Show
          Scott Carey added a comment - Thats a clean quick way to get off of Forrest. But yuck, Anakina makes ugly web pages. Tomcat and httpd look like the web in 1998. Any examples that actually look decent? We can improve the site design, look/feel/navigation any other time, for now getting rid of the Forrest mess would be a big improvement – many more people would be able to do a full build + package for testing. How important is pdf generation of docs? It is definitely nice for the Avro spec, but if the HTML version prints decently we may be able to get by for a while without it.
          Hide
          Jeff McCarrell added a comment -

          Yup, the site design is not terribly modern – tables, etc.

          re: PDF of docs
          one possibility would be to convert the docs we want in PDF, like the spec, to something else.
          Perhaps asciidoc -> DocBook -> PDF

          Show
          Jeff McCarrell added a comment - Yup, the site design is not terribly modern – tables, etc. re: PDF of docs one possibility would be to convert the docs we want in PDF, like the spec, to something else. Perhaps asciidoc -> DocBook -> PDF
          Hide
          Doug Cutting added a comment -

          I would support Jeff's proposal. It would provide a significant improvement with moderate effort. PDF is not a priority to me. I've used Anakia and it is fast and relatively painless.

          Jeff, are you volunteering to implement this?

          Or is anyone else willing to volunteer to convert the above listed documents to asciidoc or some other format?

          Show
          Doug Cutting added a comment - I would support Jeff's proposal. It would provide a significant improvement with moderate effort. PDF is not a priority to me. I've used Anakia and it is fast and relatively painless. Jeff, are you volunteering to implement this? Or is anyone else willing to volunteer to convert the above listed documents to asciidoc or some other format?
          Hide
          Jeff McCarrell added a comment -

          Yes, I am willing to do the work if the community decides this proposal is the way to go.

          Show
          Jeff McCarrell added a comment - Yes, I am willing to do the work if the community decides this proposal is the way to go.
          Hide
          Doug Cutting added a comment -

          So, unless a volunteer steps forward in the next day or so to do this differently, I say go for it.

          Show
          Doug Cutting added a comment - So, unless a volunteer steps forward in the next day or so to do this differently, I say go for it.
          Hide
          Doug Cutting added a comment -

          This should not block the 1.4.0 release.

          Show
          Doug Cutting added a comment - This should not block the 1.4.0 release.
          Hide
          Carl Steinbach added a comment -

          AVRO-718 provides a patch that makes it possible to run Forrest with JDK6.

          Show
          Carl Steinbach added a comment - AVRO-718 provides a patch that makes it possible to run Forrest with JDK6.
          Hide
          Peter Linnell added a comment -

          Update ? I'd love to see that we could drop forrest for Bigtop.

          Show
          Peter Linnell added a comment - Update ? I'd love to see that we could drop forrest for Bigtop.
          Hide
          Peter Linnell added a comment -

          Bumping. I'd love to drop Forrest from Bigtop.

          Show
          Peter Linnell added a comment - Bumping. I'd love to drop Forrest from Bigtop.

            People

            • Assignee:
              Unassigned
              Reporter:
              Jeff Hammerbacher
            • Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

              • Created:
                Updated:

                Development