javadoc-cleanup
Overview
The javadoc-cleanup GitHub Action enables creating mobile-friendly and SEO ready, documentation sites by post-processing javadocs in GitHub Actions. The javadoc-cleanup GitHub action is a utility to tidy up javadocs prior to deployment to an API documentation website, assumed hosted on GitHub Pages. It performs the following functions.
Improved mobile browsing experience: It inserts appropriate viewport directives within the head of each html file that was generated by javadoc if not already present. Beginning with Java 16+, javadoc inserts appropriate viewport declarations to begin with, but earlier Java versions do not.
Strips out any timestamps inserted by javadoc: The timestamps cause a variety of version control issues for documentation sites maintained in git repositories. Javadoc has an option -notimestamp to direct javadoc not to insert timestamps (which we recommend that you also use). However, at the present time there appears to be a bug (in OpenJDK 11's javadoc, and possibly other versions), where the timestamp is not omitted in the overview-summary.html generated by javadoc.
Canonical URL generation: It is capable of generating and inserting the canonical URL for each javadoc page.
User-defined block insertion: It enables inserting a user-defined block into the head of each javadoc generated page. For example, this feature can come in handy if you want to insert a link to your site's favicon, or really anything else that is valid in the head of an html file.
Cleans up javadoc-generated redirects: In projects that use the Java
Platform Module System (JPMS), javadoc redirects the
root index.html to the page of a module, and under certain other circumstances to a
package page. Such redirected pages should direct search engines to noindex,
but javadoc doesn't do so. The javadoc-cleanup action inserts a noindex, follow
directive in any such redirected pages.
The javadoc-cleanup GitHub Action is implemented in Python, and the source code repository is hosted on GitHub; and it is licensed under the MIT License. Also in the GitHub repository you will find detailed instructions for use including several sample GitHub workflows.
The javadoc-cleanup GitHub Action is developed by Vincent A. Cicirello. It was originally implemented for my own use, but I have decided to share it with others.
Live Examples
| Repository | Workflow | Javadocs |
|---|---|---|
| Chips-n-Salsa | docs.yml | https://chips-n-salsa.cicirello.org/api/ |
| JavaPermutationTools | docs.yml | https://jpt.cicirello.org/api/ |
Tech Stack
The javadoc-cleanup GitHub Action utilizes the following:
- Python 3 (implemented almost entirely in Python);
- The pyaction Docker container, which is a Docker container designed to support GitHub Actions development in the Python language (also see pyaction's GitHub repository);
- The cicirello/python-github-action-template repository, a template that we maintain to assist developers getting started developing a GitHub Action in Python;
- Docker since it is implemented as a container action; and
- GitHub Container Registry, which is where we pull pyaction from at runtime for faster action loading (e.g., pulling the base Docker container from GitHub while an action is running on a GitHub server should be faster than pulling from Docker Hub).
Blog Posts About javadoc-cleanup
As the author of javadoc-cleanup, I occasionally post about this, and other software that I maintain on DEV.to. See my DEV.to profile for a full list of such posts. Below is a selection of blog posts specifically about javadoc-cleanup.
Deploy a Documentation Website for a Java Library Using GitHub Actions, posted on DEV on November 30, 2022.
This post explains how to use GitHub Actions to automate deployment of a documentation website for a Java library whenever a new release is available. This workflow builds the javadocs of the library, post-processes them to insert things like a referrer policy, the website's favicon, etc, updates an XML sitemap, and finally deploys to GitHub Pages.
Post-Process Javadoc-Generated Documentation in GitHub Actions Before Deploying to the Web, posted on DEV on November 16, 2022.
This post introduces how to use javadoc-cleanup, a GitHub Action that post-processes javadoc-generated documentation to improve it in various ways prior to deployment.