Uploaded image for project: 'Hadoop Common'
  1. Hadoop Common
  2. HADOOP-9432

Add support for markdown .md files in site documentation

    Details

    • Type: New Feature
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: 3.0.0-alpha1
    • Fix Version/s: 2.3.0
    • Component/s: build, documentation
    • Labels:
      None

      Description

      The "markdown" syntax for marking up text is something which the mvn site build can be set up to support alongside the existing APT formatted text.

      Markdown offers many advantages

      1. It's more widely understood.
      2. There's tooling support in various text editors (TextMate, an IDEA plugin and others)
      3. It can be directly rendered in github
      4. the .md files can be named .md.vm to trigger velocity preprocessing, at the expense of direct viewing in github

      feature #3 is good as it means that you can point people directly at a doc via a github mirror, and have it rendered.

      I propose adding the options to Maven to enable content be written as .md and .md.vm files in the directory src/site/markdown. This does not require any changes to the existing .apt files, which can co-exist and cross-reference each other.

      1. HADOOP-9432.patch
        1.0 kB
        Steve Loughran

        Issue Links

          Activity

          Hide
          stevel@apache.org Steve Loughran added a comment -

          Patch for POM without any new markdown files to associate with it. Those could be added on request

          Show
          stevel@apache.org Steve Loughran added a comment - Patch for POM without any new markdown files to associate with it. Those could be added on request
          Hide
          hadoopqa Hadoop QA added a comment -

          +1 overall. Here are the results of testing the latest attachment
          http://issues.apache.org/jira/secure/attachment/12575316/HADOOP-9432.patch
          against trunk revision .

          +1 @author. The patch does not contain any @author tags.

          +0 tests included. The patch appears to be a documentation patch that doesn't require tests.

          +1 javac. The applied patch does not increase the total number of javac compiler warnings.

          +1 javadoc. The javadoc tool did not generate any warning messages.

          +1 eclipse:eclipse. The patch built with eclipse:eclipse.

          +1 findbugs. The patch does not introduce any new Findbugs (version 1.3.9) warnings.

          +1 release audit. The applied patch does not increase the total number of release audit warnings.

          +1 core tests. The patch passed unit tests in .

          +1 contrib tests. The patch passed contrib unit tests.

          Test results: https://builds.apache.org/job/PreCommit-HADOOP-Build/2362//testReport/
          Console output: https://builds.apache.org/job/PreCommit-HADOOP-Build/2362//console

          This message is automatically generated.

          Show
          hadoopqa Hadoop QA added a comment - +1 overall . Here are the results of testing the latest attachment http://issues.apache.org/jira/secure/attachment/12575316/HADOOP-9432.patch against trunk revision . +1 @author . The patch does not contain any @author tags. +0 tests included . The patch appears to be a documentation patch that doesn't require tests. +1 javac . The applied patch does not increase the total number of javac compiler warnings. +1 javadoc . The javadoc tool did not generate any warning messages. +1 eclipse:eclipse . The patch built with eclipse:eclipse. +1 findbugs . The patch does not introduce any new Findbugs (version 1.3.9) warnings. +1 release audit . The applied patch does not increase the total number of release audit warnings. +1 core tests . The patch passed unit tests in . +1 contrib tests . The patch passed contrib unit tests. Test results: https://builds.apache.org/job/PreCommit-HADOOP-Build/2362//testReport/ Console output: https://builds.apache.org/job/PreCommit-HADOOP-Build/2362//console This message is automatically generated.
          Hide
          cmccabe Colin P. McCabe added a comment -

          We just got done migrating from Forrest to APT. Are we going to get rid of APT now? Its time on this earth was pretty short, I guess.

          Show
          cmccabe Colin P. McCabe added a comment - We just got done migrating from Forrest to APT. Are we going to get rid of APT now? Its time on this earth was pretty short, I guess.
          Hide
          stevel@apache.org Steve Loughran added a comment -

          no, they can live happily alongside each other.

          Show
          stevel@apache.org Steve Loughran added a comment - no, they can live happily alongside each other.
          Hide
          vicaya Luke Lu added a comment -

          +1 for md and the patch.

          Show
          vicaya Luke Lu added a comment - +1 for md and the patch.
          Hide
          stevel@apache.org Steve Loughran added a comment -

          -I hadn't noticed that Luke had +1'd this; I'll commit it. What I do want to note is that while MD is generally a more widely supported format than .apt, it doesn't do tables without embedding raw HTML -and we don't want that, do we?

          Show
          stevel@apache.org Steve Loughran added a comment - -I hadn't noticed that Luke had +1'd this; I'll commit it. What I do want to note is that while MD is generally a more widely supported format than .apt, it doesn't do tables without embedding raw HTML -and we don't want that, do we?
          Hide
          vicaya Luke Lu added a comment -

          doxia markdown module is based pegdown which supports table nicely.

          Show
          vicaya Luke Lu added a comment - doxia markdown module is based pegdown which supports table nicely.
          Hide
          hudson Hudson added a comment -

          Integrated in Hadoop-trunk-Commit #4067 (See https://builds.apache.org/job/Hadoop-trunk-Commit/4067/)
          HADOOP-9432 Add support for markdown .md files in site documentation (Revision 1502251)

          Result = SUCCESS
          stevel : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251
          Files :

          • /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
          • /hadoop/common/trunk/pom.xml
          Show
          hudson Hudson added a comment - Integrated in Hadoop-trunk-Commit #4067 (See https://builds.apache.org/job/Hadoop-trunk-Commit/4067/ ) HADOOP-9432 Add support for markdown .md files in site documentation (Revision 1502251) Result = SUCCESS stevel : http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251 Files : /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt /hadoop/common/trunk/pom.xml
          Hide
          stevel@apache.org Steve Loughran added a comment -

          Committed to trunk and branch-2. For the latter I added the change to hadoop-common/CHANGES.TXT under 2.3.0 -I'm assuming that's what branch-2 is targeting

          Show
          stevel@apache.org Steve Loughran added a comment - Committed to trunk and branch-2. For the latter I added the change to hadoop-common/CHANGES.TXT under 2.3.0 -I'm assuming that's what branch-2 is targeting
          Hide
          hudson Hudson added a comment -

          SUCCESS: Integrated in Hadoop-Yarn-trunk #268 (See https://builds.apache.org/job/Hadoop-Yarn-trunk/268/)
          HADOOP-9432 Add support for markdown .md files in site documentation (stevel: http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251)

          • /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
          • /hadoop/common/trunk/pom.xml
          Show
          hudson Hudson added a comment - SUCCESS: Integrated in Hadoop-Yarn-trunk #268 (See https://builds.apache.org/job/Hadoop-Yarn-trunk/268/ ) HADOOP-9432 Add support for markdown .md files in site documentation (stevel: http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251 ) /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt /hadoop/common/trunk/pom.xml
          Hide
          hudson Hudson added a comment -

          FAILURE: Integrated in Hadoop-Hdfs-trunk #1458 (See https://builds.apache.org/job/Hadoop-Hdfs-trunk/1458/)
          HADOOP-9432 Add support for markdown .md files in site documentation (stevel: http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251)

          • /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
          • /hadoop/common/trunk/pom.xml
          Show
          hudson Hudson added a comment - FAILURE: Integrated in Hadoop-Hdfs-trunk #1458 (See https://builds.apache.org/job/Hadoop-Hdfs-trunk/1458/ ) HADOOP-9432 Add support for markdown .md files in site documentation (stevel: http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251 ) /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt /hadoop/common/trunk/pom.xml
          Hide
          hudson Hudson added a comment -

          SUCCESS: Integrated in Hadoop-Mapreduce-trunk #1485 (See https://builds.apache.org/job/Hadoop-Mapreduce-trunk/1485/)
          HADOOP-9432 Add support for markdown .md files in site documentation (stevel: http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251)

          • /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt
          • /hadoop/common/trunk/pom.xml
          Show
          hudson Hudson added a comment - SUCCESS: Integrated in Hadoop-Mapreduce-trunk #1485 (See https://builds.apache.org/job/Hadoop-Mapreduce-trunk/1485/ ) HADOOP-9432 Add support for markdown .md files in site documentation (stevel: http://svn.apache.org/viewcvs.cgi/?root=Apache-SVN&view=rev&rev=1502251 ) /hadoop/common/trunk/hadoop-common-project/hadoop-common/CHANGES.txt /hadoop/common/trunk/pom.xml

            People

            • Assignee:
              stevel@apache.org Steve Loughran
              Reporter:
              stevel@apache.org Steve Loughran
            • Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Time Tracking

                Estimated:
                Original Estimate - 0.5h
                0.5h
                Remaining:
                Remaining Estimate - 0.5h
                0.5h
                Logged:
                Time Spent - Not Specified
                Not Specified

                  Development