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:
- Improves 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.
- Capable of generating and inserting the canonical URL for each javadoc page.
- Enables inserting a user-defined block into the head of each javadoc generated page. For example, 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.
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.
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.