Merge branch 'pr-2417'

[core] Host own javadoc on docs.pmd-code.org #2417
2020-04-23 11:15:44 +02:00
parent 71884c5157 f1410752bc
commit 53f6633b4f
8 changed files with 161 additions and 28 deletions
--- a/.travis/build-doc.sh
+++ b/.travis/build-doc.sh
@ -1,10 +1,11 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -e

 source .travis/logger.sh
 source .travis/common-functions.sh
 source .travis/github-releases-api.sh
 source .travis/sourceforge-api.sh
+source .travis/pmd-code-api.sh

 function main() {
    VERSION=$(./mvnw -q -Dexec.executable="echo" -Dexec.args='${project.version}' --non-recursive org.codehaus.mojo:exec-maven-plugin:1.5.0:exec)
@ -15,7 +16,7 @@ function main() {
    # The docs should appear under "docs/pages/rules/..." for each language
    # With this profile, also the checks are executed (e.g. DeadLinksChecker).
    #
-    ./mvnw clean verify -Dmaven.test.skip=true -Dmaven.javadoc.skip=true -P generate-rule-docs
+    ./mvnw clean verify -Dmaven.test.skip=true -P generate-rule-docs

    if ! travis_isPush; then
        log_info "Not publishing site, since this is not a push!"
@ -31,9 +32,17 @@ function main() {
    # Deploy to sourceforge files
    sourceforge_uploadFile "${VERSION}" "docs/pmd-doc-${VERSION}.zip"

+    # Deploy doc to https://docs.pmd-code.org/pmd-doc-${VERSION}/
+    pmd_code_uploadDocumentation "${VERSION}" "docs/pmd-doc-${VERSION}.zip"
+    # Deploy javadoc to https://docs.pmd-code.org/apidocs/*/${VERSION}/
+    pmd_code_uploadJavadoc "${VERSION}" "$(pwd)"
+
+
    if [[ "${VERSION}" == *-SNAPSHOT && "${TRAVIS_BRANCH}" == "master" ]]; then
        # only for snapshot builds from branch master

+        pmd_code_createSymlink "${VERSION}" "snapshot"
+
        # update github pages https://pmd.github.io/pmd/
        publish_to_github_pages
        # rsync site to https://pmd.sourceforge.io/snapshot
@ -44,6 +53,14 @@ function main() {
    if [[ "${VERSION}" != *-SNAPSHOT && "${TRAVIS_TAG}" != "" ]]; then
        log_info "This is a release documentation build for pmd ${VERSION}"

+        # documentation is already uploaded to https://docs.pmd-code.org/pmd-doc-${VERSION}
+        pmd_code_createSymlink "${VERSION}" "latest"
+        # remove old doc and point to the new version
+        pmd_code_removeDocumentation "${VERSION}-SNAPSHOT"
+        pmd_code_createSymlink "${VERSION}" "${VERSION}-SNAPSHOT"
+        # remove old javadoc
+        pmd_code_removeJavadoc "${VERSION}-SNAPSHOT"
+
        # Deploy to github releases
        gh_releases_getLatestDraftRelease
        GH_RELEASE="$RESULT"
--- a/.travis/pmd-code-api.sh
+++ b/.travis/pmd-code-api.sh
@ -0,0 +1,94 @@
+#
+# The functions here require the following scripts:
+# .travis/logger.sh
+#
+
+PMD_CODE_SSH_USER=pmd
+PMD_CODE_DOCS_PATH=/docs.pmd-code.org/
+
+function pmd_code_uploadDocumentation() {
+    local pmdVersion="$1"
+    local filename="$2"
+    local basefilename="$(basename $filename)"
+
+    log_debug "$FUNCNAME pmdVersion=$pmdVersion filename=$filename"
+
+    scp "${filename}" ${PMD_CODE_SSH_USER}@pmd-code.org:${PMD_CODE_DOCS_PATH}
+    ssh ${PMD_CODE_SSH_USER}@pmd-code.org "cd ${PMD_CODE_DOCS_PATH} && \
+            unzip -qo ${basefilename} && \
+            rm ${basefilename}"
+    log_info "Docs updated: https://docs.pmd-code.org/pmd-doc-${pmdVersion}/"
+}
+
+function pmd_code_removeDocumentation() {
+    local pmdVersion="$1"
+
+    log_debug "$FUNCNAME pmdVersion=$pmdVersion"
+
+    ssh ${PMD_CODE_SSH_USER}@pmd-code.org "cd ${PMD_CODE_DOCS_PATH} && \
+            rm -rf pmd-doc-${pmdVersion}/"
+    log_info "Removed docs: https://docs.pmd-code.org/pmd-doc-${pmdVersion}/"
+}
+
+function pmd_code_createSymlink() {
+    local pmdVersion="$1"
+    local name="$2"
+
+    log_debug "$FUNCNAME pmdVersion=$pmdVersion name=$name"
+
+    ssh ${PMD_CODE_SSH_USER}@pmd-code.org "cd ${PMD_CODE_DOCS_PATH} && \
+            rm -f $name && \
+            ln -s pmd-doc-${pmdVersion} $name"
+    log_info "Symlink created: https://docs.pmd-code.org/$name/ -> https://docs.pmd-code.org/pmd-doc-${pmdVersion}/"
+}
+
+function pmd_code_uploadJavadoc() {
+    local pmdVersion="$1"
+    local basePath="$2"
+
+    log_debug "$FUNCNAME pmdVersion=$pmdVersion basePath=$basePath"
+
+    for i in ${basePath}/*/target/*-javadoc.jar; do
+        pmd_code_uploadJavadocModule "$pmdVersion" "$i"
+    done
+
+    pmd_code_fixPmdLangTestStyle "${basePath}"
+
+    # make sure https://docs.pmd-code.org/apidocs/ shows directory index
+    ssh ${PMD_CODE_SSH_USER}@pmd-code.org "cd ${PMD_CODE_DOCS_PATH}/apidocs && \
+        echo 'Options +Indexes' > .htaccess"
+    log_info "Directory index enabled for https://docs.pmd-code.org/apidocs/"
+}
+
+function pmd_code_uploadJavadocModule() {
+    local pmdVersion="$1"
+    local moduleJavadocJar="$2"
+    local moduleJavadocJarBasename="$(basename $moduleJavadocJar)"
+    local module=${moduleJavadocJarBasename%%-${pmdVersion}-javadoc.jar}
+
+    log_debug "$FUNCNAME pmdVersion=$pmdVersion moduleJavadocJar=$moduleJavadocJar module=$module"
+
+    scp "$moduleJavadocJar" ${PMD_CODE_SSH_USER}@pmd-code.org:${PMD_CODE_DOCS_PATH}
+    ssh ${PMD_CODE_SSH_USER}@pmd-code.org "cd ${PMD_CODE_DOCS_PATH} && \
+            mkdir -p apidocs/${module}/${pmdVersion} && \
+            unzip -qo -d apidocs/${module}/${pmdVersion} ${moduleJavadocJarBasename} && \
+            rm ${moduleJavadocJarBasename}"
+    log_info "JavaDoc for $module uploaded: https://docs.pmd-code.org/apidocs/${module}/${pmdVersion}/"
+}
+
+function pmd_code_fixPmdLangTestStyle {
+    local basePath="$1"
+
+    log_debug "$FUNCNAME basePath=$basePath"
+    scp "${basePath}/pmd-lang-test/target/dokka/style.css" ${PMD_CODE_SSH_USER}@pmd-code.org:${PMD_CODE_DOCS_PATH}/apidocs/pmd-lang-test/
+    log_info "Fixed style for https://docs.pmd-code.org/apidocs/pmd-lang-test/*/"
+}
+
+function pmd_code_removeJavadoc() {
+    local pmdVersion="$1"
+
+    log_debug "$FUNCNAME pmdVersion=$pmdVersion"
+    ssh ${PMD_CODE_SSH_USER}@pmd-code.org "cd ${PMD_CODE_DOCS_PATH} && \
+            rm -rf apidocs/*/${pmdVersion}"
+    log_info "Removed Javadoc: https://docs.pmd-code.org/apidocs/*/${pmdVersion}/ is gone"
+}
--- a/.travis/setup-secrets.sh
+++ b/.travis/setup-secrets.sh
@ -61,3 +61,5 @@ echo 'web.sourceforge.net ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA2uifHZbNexw6cXbyg1
 echo 'web.sourceforge.net ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBCwsY6sZT4MTTkHfpRzYjxG7mnXrGL74RCT2cO/NFvRrZVNB5XNwKNn7G5fHbYLdJ6UzpURDRae1eMg92JG0+yo=' >> "$HOME/.ssh/known_hosts"
 echo 'web.sourceforge.net ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOQD35Ujalhh+JJkPvMckDlhu4dS7WH6NsOJ15iGCJLC' >> "$HOME/.ssh/known_hosts"

+# add pmd-code.org (ssh-keyscan pmd-code.org)
+echo 'pmd-code.org ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVsIeF6xU0oPb/bMbxG1nU1NDyBpR/cBEPZcm/PuJwdI9B0ydPHA6FysqAnt32fNFznC2SWisnWyY3iNsP3pa8RQJVwmnnv9OboGFlW2/61o3iRyydcpPbgl+ADdt8iU9fmMI7dC04UqgHGBoqOwVNna9VylTjp5709cK2qHnwU450F6YcOEiOKeZfJvV4PmpJCz/JcsUVqft6StviR31jKnqbnkZdP8qNoTbds6WmGKyXkhHdLSZE7X1CFQH28tk8XFqditX93ezeCiThFL7EleDexV/3+2+cs5878sDMUMzHS5KShTjkxzhHaodhtIEdNesinq/hOPbxAGkQ0FbD' >> $HOME/.ssh/known_hosts
--- a/docs/_config.yml
+++ b/docs/_config.yml
@ -1,7 +1,7 @@
 repository: pmd/pmd

 pmd:
-    version: 6.23.0
+    version: 6.23.0-SNAPSHOT
    previous_version: 6.22.0
    date: ??-??-2020
    release_type: minor
@ -115,3 +115,7 @@ description: "Intended as a documentation theme based on Jekyll for technical wr
 # needed for sitemap.xml file only
 url: https://pmd.github.io/pmd
 baseurl: ""
+
+# used by javadoc_tag.rb
+# https://javadoc.io/page/net.sourceforge.pmd
+javadoc_url_prefix: https://docs.pmd-code.org/apidocs
--- a/docs/_plugins/javadoc_tag.rb
+++ b/docs/_plugins/javadoc_tag.rb
@ -151,13 +151,13 @@ class JavadocTag < Liquid::Tag
    api_version = var_ctx["site.pmd." + (@use_previous_api_version ? "previous_version" : "version")]


-    markup_link(visible_name, doclink(artifact_name, api_version, @type_fqcn, @member_suffix))
+    markup_link(visible_name, doclink(var_ctx["site.javadoc_url_prefix"], artifact_name, api_version, @type_fqcn, @member_suffix))
  end

  private

-  def doclink(artifact, api_version, type_name, member_suffix)
-    "https://javadoc.io/page/net.sourceforge.pmd/#{artifact}/#{api_version}/#{type_name.gsub("\.", "/")}.html##{member_suffix}"
+  def doclink(url_prefix, artifact, api_version, type_name, member_suffix)
+    "#{url_prefix}/#{artifact}/#{api_version}/#{type_name.gsub("\.", "/")}.html##{member_suffix}"
  end

  def markup_link(rname, link)
--- a/docs/pages/pmd/projectdocs/committers/releasing.md
+++ b/docs/pages/pmd/projectdocs/committers/releasing.md
@ -27,13 +27,14 @@ Make sure code is up to date and everything is committed and pushed with git:

 You can find the release notes here: `docs/pages/release_notes.md`.

-The date and the version must be updated in `docs/_config.yml`,  e.g.
+The date (`date +%d-%B-%Y`) and the version (remove the SNAPSHOT) must be updated in `docs/_config.yml`,  e.g.

 ```
 pmd:
-    version: 6.0.0
-    date: 2017-12-15
-    release_type: major
+    version: 6.22.0
+    previous_version: 6.21.0
+    date: 12-March-2020
+    release_type: minor
 ```

 The release type could be one of "bugfix", "minor", or "major".
@ -86,13 +87,13 @@ The new version needs to be entered into `_config.yml`, e.g.:

 ```
 pmd:
-  latestVersion: 6.0.0
-  latestVersionDate: 15th December 2017
+  latestVersion: 6.22.0
+  latestVersionDate: 12-March-2020
 ```

 Also move the previous version down into the "downloads" section.

-Then create a new page for the new release, e.g. `_posts/2017-12-15-PMD-6.0.0.md` and copy
+Then create a new page for the new release, e.g. `_posts/2020-03-12-PMD-6.22.0.md` and copy
 the release notes into this page. This will appear under the news section.

 Check in all (version) changes to branch master:
@ -131,6 +132,7 @@ it is a tag build and a released version build, travis-ci will do a couple of ad
    selected as the new default downloads for PMD.
 *   Add the documentation of the new release to a subfolder on <https://pmd.github.io>, also make
    this folder available as `latest`.
+*   Upload the documentation to <https://docs.pmd-code.org>.


 ## After the release
@ -165,7 +167,16 @@ the following template:

 ### Prepare the new release notes

-*   Update version in **docs/_config.yml**
+*   Update version in **docs/_config.yml**. Note - the next version needs to have a SNAPSHOT in it.
+    
+    ```
+    pmd:
+        version: 6.23.0-SNAPSHOT
+        previous_version: 6.22.0
+        date: ??-??-2020
+        release_type: minor
+    ```
+
 *   Move version/release info from **docs/pages/release_notes.md** to **docs/pages/release_notes_old.md**.
 *   Update version/release info in **docs/pages/release_notes.md**. Use the following template:

--- a/pmd-lang-test/pom.xml
+++ b/pmd-lang-test/pom.xml
@ -72,7 +72,7 @@
                            <goal>jar</goal>
                        </goals>
                        <configuration>
-                            <classesDirectory>${project.build.directory}/dokka</classesDirectory>
+                            <classesDirectory>${project.build.directory}/dokka/pmd-lang-test</classesDirectory>
                            <classifier>javadoc</classifier>
                        </configuration>
                    </execution>
--- a/pom.xml
+++ b/pom.xml
@ -87,7 +87,7 @@

        <kotlin.compiler.jvmTarget>${maven.compiler.test.target}</kotlin.compiler.jvmTarget>
        <kotlin.version>1.3.0</kotlin.version>
-        <dokka.version>0.10.0</dokka.version>
+        <dokka.version>0.10.1</dokka.version>


        <javacc.version>5.0</javacc.version>
@ -96,7 +96,7 @@
        <checkstyle.plugin.version>3.1.1</checkstyle.plugin.version>
        <pmd.plugin.version>3.13.0</pmd.plugin.version>
        <ant.version>1.10.1</ant.version>
-        <javadoc.plugin.version>3.1.1</javadoc.plugin.version>
+        <javadoc.plugin.version>3.2.0</javadoc.plugin.version>
        <antlr.version>4.7</antlr.version>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
@ -278,18 +278,23 @@
                    <configuration>
                        <quiet>true</quiet>
                        <doclint>none</doclint>
-                        <additionalJOptions>
-                            <additionalJOption>-html5</additionalJOption>
-                        </additionalJOptions>
-                        <additionalDependencies>
-                            <!-- TODO: this is only needed to make javadoc happy -->
-                            <additionalDependency>
-                                <groupId>org.apache.ant</groupId>
-                                <artifactId>ant</artifactId>
-                                <version>${ant.version}</version>
-                            </additionalDependency>
-                        </additionalDependencies>
+                        <excludePackageNames>*.internal</excludePackageNames>
                        <detectOfflineLinks>false</detectOfflineLinks>
+                        <offlineLinks>
+                            <offlineLink>
+                                <location>${project.basedir}/../pmd-lang-test/target/dokka/pmd-lang-test</location>
+                                <url>../../pmd-lang-test/${project.version}</url>
+                            </offlineLink>
+                            <offlineLink>
+                                <location>${project.basedir}/../pmd-test/target/apidocs</location>
+                                <url>../../pmd-test/${project.version}</url>
+                            </offlineLink>
+                            <!-- core needs to be last, because the package "net.sourceforge.pmd.lang" is both in pmd-core and pmd-test -->
+                            <offlineLink>
+                                <location>${project.basedir}/../pmd-core/target/apidocs</location>
+                                <url>../../pmd-core/${project.version}</url>
+                            </offlineLink>
+                        </offlineLinks>
                    </configuration>
                </plugin>
                <plugin>