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

In-page TOC of documentation should be automatically generated by doxia macro

    Details

    • Type: Improvement
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 2.7.1
    • Fix Version/s: 2.8.0, 3.0.0-alpha1
    • Component/s: documentation
    • Labels:
      None
    • Target Version/s:
    • Hadoop Flags:
      Reviewed

      Description

      In-page TOC of each documentation page is maintained by hand now. It should be automatically generated once doxia macro is supported by doxia-module-markdown.

      1. HADOOP-12470.001.patch
        25 kB
        Masatake Iwasaki

        Issue Links

          Activity

          Hide
          iwasakims Masatake Iwasaki added a comment -

          The downside of this is that TOC can not be seen before compiling (e.g. by github source browser) but I think ease of maintenance weighs over it.

          Show
          iwasakims Masatake Iwasaki added a comment - The downside of this is that TOC can not be seen before compiling (e.g. by github source browser) but I think ease of maintenance weighs over it.
          Hide
          iwasakims Masatake Iwasaki added a comment -

          Since maven-site-plugin 3.5 was released, we can use toc macro in Markdown. We need to bump the version of maven-stylus-skin along with maven-site-plugin otherwise build fails.

          Show
          iwasakims Masatake Iwasaki added a comment - Since maven-site-plugin 3.5 was released, we can use toc macro in Markdown. We need to bump the version of maven-stylus-skin along with maven-site-plugin otherwise build fails.
          Hide
          iwasakims Masatake Iwasaki added a comment -
          Show
          iwasakims Masatake Iwasaki added a comment - I uploaded built docs for reviewer's convenience: trunk: https://iwasakims.github.io/trunk/hadoop-project/ patched: https://iwasakims.github.io/HADOOP-12470/hadoop-project/
          Hide
          hadoopqa Hadoop QA added a comment -
          -1 overall



          Vote Subsystem Runtime Comment
          0 reexec 0m 13s Docker mode activated.
          +1 @author 0m 0s The patch does not contain any @author tags.
          -1 test4tests 0m 0s The patch doesn't appear to include any new or modified tests. Please justify why no new tests are needed for this patch. Also please list what manual steps were performed to verify this patch.
          0 mvndep 0m 49s Maven dependency ordering for branch
          +1 mvninstall 6m 42s trunk passed
          +1 compile 5m 44s trunk passed with JDK v1.8.0_72
          +1 compile 6m 34s trunk passed with JDK v1.7.0_95
          +1 mvnsite 9m 11s trunk passed
          +1 mvneclipse 0m 39s trunk passed
          +1 javadoc 5m 21s trunk passed with JDK v1.8.0_72
          +1 javadoc 9m 25s trunk passed with JDK v1.7.0_95
          0 mvndep 0m 16s Maven dependency ordering for patch
          +1 mvninstall 9m 58s the patch passed
          +1 compile 5m 36s the patch passed with JDK v1.8.0_72
          +1 javac 5m 36s the patch passed
          +1 compile 6m 41s the patch passed with JDK v1.7.0_95
          +1 javac 6m 41s the patch passed
          +1 mvnsite 8m 56s the patch passed
          +1 mvneclipse 0m 38s the patch passed
          +1 whitespace 0m 0s Patch has no whitespace issues.
          +1 xml 0m 4s The patch has no ill-formed XML file.
          +1 javadoc 5m 17s the patch passed with JDK v1.8.0_72
          +1 javadoc 9m 17s the patch passed with JDK v1.7.0_95
          -1 unit 160m 19s root in the patch failed with JDK v1.8.0_72.
          -1 unit 85m 21s root in the patch failed with JDK v1.7.0_95.
          +1 asflicense 0m 29s Patch does not generate ASF License warnings.
          338m 36s



          Reason Tests
          JDK v1.8.0_72 Failed junit tests hadoop.yarn.server.resourcemanager.TestClientRMTokens
            hadoop.yarn.server.resourcemanager.TestAMAuthorization
          JDK v1.7.0_95 Failed junit tests hadoop.hdfs.TestDFSUpgradeFromImage
            hadoop.hdfs.server.balancer.TestBalancerWithMultipleNameNodes
            hadoop.yarn.server.resourcemanager.TestClientRMTokens
            hadoop.yarn.server.resourcemanager.TestAMAuthorization



          Subsystem Report/Notes
          Docker Image:yetus/hadoop:0ca8df7
          JIRA Patch URL https://issues.apache.org/jira/secure/attachment/12790867/HADOOP-12470.001.patch
          JIRA Issue HADOOP-12470
          Optional Tests asflicense mvnsite xml compile javac javadoc mvninstall unit
          uname Linux 5ee553f1d5ce 3.13.0-36-lowlatency #63-Ubuntu SMP PREEMPT Wed Sep 3 21:56:12 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux
          Build tool maven
          Personality /testptch/hadoop/patchprocess/precommit/personality/provided.sh
          git revision trunk / 27e0681
          Default Java 1.7.0_95
          Multi-JDK versions /usr/lib/jvm/java-8-oracle:1.8.0_72 /usr/lib/jvm/java-7-openjdk-amd64:1.7.0_95
          unit https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.8.0_72.txt
          unit https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.7.0_95.txt
          unit test logs https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.8.0_72.txt https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.7.0_95.txt
          JDK v1.7.0_95 Test Results https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/testReport/
          modules C: hadoop-project hadoop-common-project/hadoop-auth hadoop-common-project/hadoop-common hadoop-common-project/hadoop-kms hadoop-hdfs-project/hadoop-hdfs hadoop-hdfs-project/hadoop-hdfs-httpfs hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core hadoop-tools/hadoop-openstack . U: .
          Console output https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/console
          Powered by Apache Yetus 0.3.0-SNAPSHOT http://yetus.apache.org

          This message was automatically generated.

          Show
          hadoopqa Hadoop QA added a comment - -1 overall Vote Subsystem Runtime Comment 0 reexec 0m 13s Docker mode activated. +1 @author 0m 0s The patch does not contain any @author tags. -1 test4tests 0m 0s The patch doesn't appear to include any new or modified tests. Please justify why no new tests are needed for this patch. Also please list what manual steps were performed to verify this patch. 0 mvndep 0m 49s Maven dependency ordering for branch +1 mvninstall 6m 42s trunk passed +1 compile 5m 44s trunk passed with JDK v1.8.0_72 +1 compile 6m 34s trunk passed with JDK v1.7.0_95 +1 mvnsite 9m 11s trunk passed +1 mvneclipse 0m 39s trunk passed +1 javadoc 5m 21s trunk passed with JDK v1.8.0_72 +1 javadoc 9m 25s trunk passed with JDK v1.7.0_95 0 mvndep 0m 16s Maven dependency ordering for patch +1 mvninstall 9m 58s the patch passed +1 compile 5m 36s the patch passed with JDK v1.8.0_72 +1 javac 5m 36s the patch passed +1 compile 6m 41s the patch passed with JDK v1.7.0_95 +1 javac 6m 41s the patch passed +1 mvnsite 8m 56s the patch passed +1 mvneclipse 0m 38s the patch passed +1 whitespace 0m 0s Patch has no whitespace issues. +1 xml 0m 4s The patch has no ill-formed XML file. +1 javadoc 5m 17s the patch passed with JDK v1.8.0_72 +1 javadoc 9m 17s the patch passed with JDK v1.7.0_95 -1 unit 160m 19s root in the patch failed with JDK v1.8.0_72. -1 unit 85m 21s root in the patch failed with JDK v1.7.0_95. +1 asflicense 0m 29s Patch does not generate ASF License warnings. 338m 36s Reason Tests JDK v1.8.0_72 Failed junit tests hadoop.yarn.server.resourcemanager.TestClientRMTokens   hadoop.yarn.server.resourcemanager.TestAMAuthorization JDK v1.7.0_95 Failed junit tests hadoop.hdfs.TestDFSUpgradeFromImage   hadoop.hdfs.server.balancer.TestBalancerWithMultipleNameNodes   hadoop.yarn.server.resourcemanager.TestClientRMTokens   hadoop.yarn.server.resourcemanager.TestAMAuthorization Subsystem Report/Notes Docker Image:yetus/hadoop:0ca8df7 JIRA Patch URL https://issues.apache.org/jira/secure/attachment/12790867/HADOOP-12470.001.patch JIRA Issue HADOOP-12470 Optional Tests asflicense mvnsite xml compile javac javadoc mvninstall unit uname Linux 5ee553f1d5ce 3.13.0-36-lowlatency #63-Ubuntu SMP PREEMPT Wed Sep 3 21:56:12 UTC 2014 x86_64 x86_64 x86_64 GNU/Linux Build tool maven Personality /testptch/hadoop/patchprocess/precommit/personality/provided.sh git revision trunk / 27e0681 Default Java 1.7.0_95 Multi-JDK versions /usr/lib/jvm/java-8-oracle:1.8.0_72 /usr/lib/jvm/java-7-openjdk-amd64:1.7.0_95 unit https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.8.0_72.txt unit https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.7.0_95.txt unit test logs https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.8.0_72.txt https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/artifact/patchprocess/patch-unit-root-jdk1.7.0_95.txt JDK v1.7.0_95 Test Results https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/testReport/ modules C: hadoop-project hadoop-common-project/hadoop-auth hadoop-common-project/hadoop-common hadoop-common-project/hadoop-kms hadoop-hdfs-project/hadoop-hdfs hadoop-hdfs-project/hadoop-hdfs-httpfs hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core hadoop-tools/hadoop-openstack . U: . Console output https://builds.apache.org/job/PreCommit-HADOOP-Build/8761/console Powered by Apache Yetus 0.3.0-SNAPSHOT http://yetus.apache.org This message was automatically generated.
          Hide
          ajisakaa Akira Ajisaka added a comment -

          The downside of this is that TOC can not be seen before compiling (e.g. by github source browser) but I think ease of maintenance weighs over it.

          Agree. We should avoid editing TOC manually.
          The patch looks good to me, +1.

          Show
          ajisakaa Akira Ajisaka added a comment - The downside of this is that TOC can not be seen before compiling (e.g. by github source browser) but I think ease of maintenance weighs over it. Agree. We should avoid editing TOC manually. The patch looks good to me, +1.
          Hide
          hudson Hudson added a comment -

          FAILURE: Integrated in Hadoop-trunk-Commit #9423 (See https://builds.apache.org/job/Hadoop-trunk-Commit/9423/)
          HADOOP-12470. In-page TOC of documentation should be automatically (iwasakims: rev cbd31328a61252f253aa2bcdb9cad70f7876d231)

          • hadoop-common-project/hadoop-common/src/site/site.xml
          • hadoop-hdfs-project/hadoop-hdfs-httpfs/src/site/site.xml
          • hadoop-common-project/hadoop-common/src/site/markdown/SecureMode.md
          • hadoop-hdfs-project/hadoop-hdfs/src/site/site.xml
          • hadoop-common-project/hadoop-common/src/site/markdown/RackAwareness.md
          • hadoop-common-project/hadoop-common/src/site/markdown/CommandsManual.md
          • hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/site.xml
          • hadoop-common-project/hadoop-common/src/site/markdown/Metrics.md
          • hadoop-common-project/hadoop-common/src/site/markdown/ClusterSetup.md
          • hadoop-common-project/hadoop-common/src/site/markdown/Superusers.md
          • hadoop-common-project/hadoop-common/src/site/markdown/HttpAuthentication.md
          • hadoop-common-project/hadoop-kms/src/site/site.xml
          • hadoop-common-project/hadoop-common/src/site/markdown/InterfaceClassification.md
          • hadoop-common-project/hadoop-common/src/site/markdown/FileSystemShell.md
          • hadoop-common-project/hadoop-auth/src/site/site.xml
          • hadoop-common-project/hadoop-common/src/site/markdown/ServiceLevelAuth.md
          • hadoop-common-project/hadoop-common/src/site/markdown/Tracing.md
          • hadoop-common-project/hadoop-common/src/site/markdown/UnixShellGuide.md
          • hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/site/site.xml
          • hadoop-project/src/site/site.xml
          • pom.xml
          • hadoop-common-project/hadoop-common/src/site/markdown/Compatibility.md
          • hadoop-common-project/hadoop-common/src/site/markdown/CredentialProviderAPI.md
          • hadoop-common-project/hadoop-common/src/site/markdown/NativeLibraries.md.vm
          • hadoop-tools/hadoop-openstack/src/site/site.xml
          • hadoop-common-project/hadoop-common/src/site/markdown/SingleCluster.md.vm
          • hadoop-common-project/hadoop-common/src/site/markdown/CLIMiniCluster.md.vm
          Show
          hudson Hudson added a comment - FAILURE: Integrated in Hadoop-trunk-Commit #9423 (See https://builds.apache.org/job/Hadoop-trunk-Commit/9423/ ) HADOOP-12470 . In-page TOC of documentation should be automatically (iwasakims: rev cbd31328a61252f253aa2bcdb9cad70f7876d231) hadoop-common-project/hadoop-common/src/site/site.xml hadoop-hdfs-project/hadoop-hdfs-httpfs/src/site/site.xml hadoop-common-project/hadoop-common/src/site/markdown/SecureMode.md hadoop-hdfs-project/hadoop-hdfs/src/site/site.xml hadoop-common-project/hadoop-common/src/site/markdown/RackAwareness.md hadoop-common-project/hadoop-common/src/site/markdown/CommandsManual.md hadoop-yarn-project/hadoop-yarn/hadoop-yarn-site/src/site/site.xml hadoop-common-project/hadoop-common/src/site/markdown/Metrics.md hadoop-common-project/hadoop-common/src/site/markdown/ClusterSetup.md hadoop-common-project/hadoop-common/src/site/markdown/Superusers.md hadoop-common-project/hadoop-common/src/site/markdown/HttpAuthentication.md hadoop-common-project/hadoop-kms/src/site/site.xml hadoop-common-project/hadoop-common/src/site/markdown/InterfaceClassification.md hadoop-common-project/hadoop-common/src/site/markdown/FileSystemShell.md hadoop-common-project/hadoop-auth/src/site/site.xml hadoop-common-project/hadoop-common/src/site/markdown/ServiceLevelAuth.md hadoop-common-project/hadoop-common/src/site/markdown/Tracing.md hadoop-common-project/hadoop-common/src/site/markdown/UnixShellGuide.md hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/site/site.xml hadoop-project/src/site/site.xml pom.xml hadoop-common-project/hadoop-common/src/site/markdown/Compatibility.md hadoop-common-project/hadoop-common/src/site/markdown/CredentialProviderAPI.md hadoop-common-project/hadoop-common/src/site/markdown/NativeLibraries.md.vm hadoop-tools/hadoop-openstack/src/site/site.xml hadoop-common-project/hadoop-common/src/site/markdown/SingleCluster.md.vm hadoop-common-project/hadoop-common/src/site/markdown/CLIMiniCluster.md.vm
          Hide
          iwasakims Masatake Iwasaki added a comment -

          Committed to branch-2.8 and above. Thanks for the review, Akira Ajisaka!

          Show
          iwasakims Masatake Iwasaki added a comment - Committed to branch-2.8 and above. Thanks for the review, Akira Ajisaka !
          Hide
          aw Allen Wittenauer added a comment -

          Hmm.

          The bummer about this is that making the TOC a doxia macro means that if something else is processing the markdown (e.g., github), no TOC is generated/available.

          Show
          aw Allen Wittenauer added a comment - Hmm. The bummer about this is that making the TOC a doxia macro means that if something else is processing the markdown (e.g., github), no TOC is generated/available.
          Hide
          iwasakims Masatake Iwasaki added a comment -

          There is a trade-off but I think manually maintaining toc is too much burden. Toc had been generated by doxia macro before migration from apt to markdown. Part of toc have been outdated after the migration.

          Show
          iwasakims Masatake Iwasaki added a comment - There is a trade-off but I think manually maintaining toc is too much burden. Toc had been generated by doxia macro before migration from apt to markdown. Part of toc have been outdated after the migration.

            People

            • Assignee:
              iwasakims Masatake Iwasaki
              Reporter:
              iwasakims Masatake Iwasaki
            • Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development