From 545218a0c6fdd0af9797f5e483a1fd20d316313b Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 14 Apr 2020 11:15:04 +0200 Subject: [PATCH 1/7] javadoc: Upgrade javadoc plugin --- pom.xml | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/pom.xml b/pom.xml index 3252464717..74aa36e2cc 100644 --- a/pom.xml +++ b/pom.xml @@ -96,7 +96,7 @@ 3.1.1 3.13.0 1.10.1 - 3.1.1 + 3.2.0 4.7 UTF-8 @@ -278,17 +278,6 @@ true none - - -html5 - - - - - org.apache.ant - ant - ${ant.version} - - false From 93ededa5c42d236de7838fed41750fe0ef450825 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 14 Apr 2020 15:23:14 +0200 Subject: [PATCH 2/7] javadoc: add offline links between the modules and pmd-core and pmd-test --- pom.xml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/pom.xml b/pom.xml index 74aa36e2cc..8360086e70 100644 --- a/pom.xml +++ b/pom.xml @@ -279,6 +279,17 @@ true none false + + + ${project.basedir}/../pmd-test/target/apidocs + ../../pmd-test/${project.version} + + + + ${project.basedir}/../pmd-core/target/apidocs + ../../pmd-core/${project.version} + + From ae958fba7b7ec228013efd7d6c6c907c4aeb0f3c Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 14 Apr 2020 15:24:38 +0200 Subject: [PATCH 3/7] javadoc: exclude *.internal packages --- pom.xml | 1 + 1 file changed, 1 insertion(+) diff --git a/pom.xml b/pom.xml index 8360086e70..7b9ea801c4 100644 --- a/pom.xml +++ b/pom.xml @@ -278,6 +278,7 @@ true none + *.internal false From 61321c88f15648649316ba5f341e53205e2533a3 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 14 Apr 2020 15:47:36 +0200 Subject: [PATCH 4/7] javadoc: add pmd-lang-test --- pmd-lang-test/pom.xml | 2 +- pom.xml | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/pmd-lang-test/pom.xml b/pmd-lang-test/pom.xml index 2de8d05bb9..81602e16bb 100644 --- a/pmd-lang-test/pom.xml +++ b/pmd-lang-test/pom.xml @@ -72,7 +72,7 @@ jar - ${project.build.directory}/dokka + ${project.build.directory}/dokka/pmd-lang-test javadoc diff --git a/pom.xml b/pom.xml index 7b9ea801c4..aa600a52d5 100644 --- a/pom.xml +++ b/pom.xml @@ -87,7 +87,7 @@ ${maven.compiler.test.target} 1.3.0 - 0.10.0 + 0.10.1 5.0 @@ -281,6 +281,10 @@ *.internal false + + ${project.basedir}/../pmd-lang-test/target/dokka/pmd-lang-test + ../../pmd-lang-test/${project.version} + ${project.basedir}/../pmd-test/target/apidocs ../../pmd-test/${project.version} From 727c39832661510bcfe3342a87b7886cec0a65ef Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 14 Apr 2020 17:19:13 +0200 Subject: [PATCH 5/7] [ci] Upload docs and javadocs to https://docs.pmd-code.org --- .travis/build-doc.sh | 21 +++++++++- .travis/pmd-code-api.sh | 84 ++++++++++++++++++++++++++++++++++++++++ .travis/setup-secrets.sh | 2 + 3 files changed, 105 insertions(+), 2 deletions(-) create mode 100644 .travis/pmd-code-api.sh diff --git a/.travis/build-doc.sh b/.travis/build-doc.sh index 9a5f00a8c7..1d81fd2bff 100755 --- 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" diff --git a/.travis/pmd-code-api.sh b/.travis/pmd-code-api.sh new file mode 100644 index 0000000000..55920c24e0 --- /dev/null +++ b/.travis/pmd-code-api.sh @@ -0,0 +1,84 @@ +# +# 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 + + # 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_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" +} diff --git a/.travis/setup-secrets.sh b/.travis/setup-secrets.sh index 493ece7f6d..2900e459f3 100755 --- 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 From 92466ebd285862fa5c248f23c172c6d8c44d7a57 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 14 Apr 2020 17:40:29 +0200 Subject: [PATCH 6/7] [doc] Use new javadoc location from https://docs.pmd-code.org Note: the version now needs SNAPSHOT, so that the javadoc links work on master. This is not available, if javadoc.io is used. --- docs/_config.yml | 6 ++++- docs/_plugins/javadoc_tag.rb | 6 ++--- .../pmd/projectdocs/committers/releasing.md | 27 +++++++++++++------ 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/docs/_config.yml b/docs/_config.yml index 6096f80ba3..ca07e857f0 100644 --- 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 diff --git a/docs/_plugins/javadoc_tag.rb b/docs/_plugins/javadoc_tag.rb index 11fc919b94..f8ee9e7f30 100644 --- 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) diff --git a/docs/pages/pmd/projectdocs/committers/releasing.md b/docs/pages/pmd/projectdocs/committers/releasing.md index 0951ac7e16..1fa2713893 100644 --- 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". @@ -67,13 +68,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: @@ -112,6 +113,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 , also make this folder available as `latest`. +* Upload the documentation to . ## After the release @@ -146,7 +148,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: From f1410752bc6d3eba18578d5b1e776c7422d694f7 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 14 Apr 2020 17:51:21 +0200 Subject: [PATCH 7/7] [ci] Fixed style for pmd-lang-test --- .travis/pmd-code-api.sh | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.travis/pmd-code-api.sh b/.travis/pmd-code-api.sh index 55920c24e0..7a35523941 100644 --- a/.travis/pmd-code-api.sh +++ b/.travis/pmd-code-api.sh @@ -52,6 +52,8 @@ function pmd_code_uploadJavadoc() { 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" @@ -74,6 +76,14 @@ function pmd_code_uploadJavadocModule() { 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"