DEV Community

Cover image for Post-Process Javadoc-Generated Documentation in GitHub Actions Before Deploying to the Web
Vincent A. Cicirello
Vincent A. Cicirello

Posted on

Post-Process Javadoc-Generated Documentation in GitHub Actions Before Deploying to the Web

This post introduces javadoc-cleanup, a GitHub Action that I developed a while ago for post-processing javadoc documentation prior to deploying to a documentation website. I use it in several of my own Java projects to improve the output of javadoc in a few ways. The functionality of javadoc-cleanup includes the following:

  • For pre-Java 16 projects, it inserts a viewport meta tag, <meta name="viewport" content="width=device-width, initial-scale=1">, into the head of each javadoc page to improve mobile browsing. Beginning with Java 16, this isn't necessary as javadoc began including the viewport meta tag beginning with Java 16.
  • Option to generate and insert canonical URLs into the head of each page.
  • Option to insert a user-defined block into the head of each page. You can use this feature to insert anything that is valid in the head of an HTML page into the head of each javadoc page. I use this feature to set a referrer policy, to insert a link to my site's favicon, and to set my web monetization pointer.
  • A few other minor cleanup actions that vary based on version of javadoc in use and other project specific characteristics. For example, if the project is a Java library using Java Platform Module System (JPMS), javadoc-cleanup will insert a noindex directive in the root level index.html. This is because for JPMS projects that javadoc generated index.html page uses a simple redirect to the page documenting the module, and javadoc also sets the module page's url as canonical. Thus, the page documenting the module should ideally be indexed, but not the redirect.

Table of Contents: This post is organized as follows:

Usage

Here is an example GitHub workflow step:

    - name: Tidy up the javadocs
      uses: cicirello/javadoc-cleanup@v1
      with:
        path-to-root: docs
        base-url-path: https://www.example.com/
        user-defined-block: |
          <meta name="referrer" content="strict-origin-when-cross-origin">
          <link rel="icon" href="/images/favicon.svg" sizes="any" type="image/svg+xml">
Enter fullscreen mode Exit fullscreen mode

The above step demonstrates using all of the inputs to the action.

  • The path-to-root input is used to specify the path to the root of the documentation website relative to the root of the repository. This input is optional, and defaults to the root of the repository. Note that this input should specify the root of the documentation website, which may or may not be the root of the javadocs themselves. For example, if you have the javadocs in a subdirectory, you should specify the parent and not the subdirectory containing the javadocs, or else the canonical links to the javadoc pages will be incorrect. The javadoc-cleanup action itself will simply skip any HTML files that were not generated by javadoc (e.g., before making any modifications, it examines the head of an HTML page for the presence of the comment that javadoc inserts into pages it generates).
  • The base-url-path input is used to enable the optional insertion of canonical links. Just leave this input out if you don't want to insert canonical links.
  • The user-defined-block input is optional, and is used to insert whatever you want into the head of every javadoc page. In the example above, it demonstrates inserting a link to a favicon for the site, as well as inserting a referrer policy.

See javadoc-cleanup's GitHub repository for example workflows that utilize it.

Learn More

You can find more information about this GitHub Action in its GitHub repository:

GitHub logo cicirello / javadoc-cleanup

Create mobile-friendly documentation sites by post-processing javadocs in GitHub Actions

javadoc-cleanup

cicirello/javadoc-cleanup - Create mobile-friendly documentation sites by post-processing javadocs in GitHub Actions

Check out all of our GitHub Actions: https://actions.cicirello.org/

About

GitHub Actions GitHub release (latest by date) Count of Action Users
Build Status build CodeQL
Source Info License GitHub top language
Support GitHub Sponsors Liberapay Ko-Fi

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 <meta name="viewport" content="width=device-width, initial-scale=1"> within the <head> of each html file that was generated by javadoc, if not already present. Beginning with Java 16, javadoc properly defines the viewport, whereas prior to Java 16, it does 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)…

You can also find information about this GitHub Action, as well as others I've implemented and maintain at the following site:

Vincent Cicirello - Open source GitHub Actions for workflow automation

Features information on several open source GitHub Actions for workflow automation that we have developed to automate parts of the CI/CD pipeline, and other repetitive tasks. The GitHub Actions featured include jacoco-badge-generator, generate-sitemap, user-statistician, and javadoc-cleanup.

favicon actions.cicirello.org

Where You Can Find Me

Follow me here on DEV:

Follow me on GitHub:

GitHub logo cicirello / cicirello

My GitHub Profile

Vincent A Cicirello

Vincent A. Cicirello

Sites where you can find me or my work
Web and social media Personal Website LinkedIn DEV Profile
Software development Github Maven Central PyPI Docker Hub
Publications Google Scholar ORCID DBLP ACM Digital Library IEEE Xplore ResearchGate arXiv

My bibliometrics

My GitHub Activity

If you want to generate the equivalent to the above for your own GitHub profile, check out the cicirello/user-statistician GitHub Action.




Or visit my website:

Vincent A. Cicirello - Professor of Computer Science

Vincent A. Cicirello - Professor of Computer Science at Stockton University - is a researcher in artificial intelligence, evolutionary computation, swarm intelligence, and computational intelligence, with a Ph.D. in Robotics from Carnegie Mellon University. He is an ACM Senior Member, IEEE Senior Member, AAAI Life Member, EAI Distinguished Member, and SIAM Member.

favicon cicirello.org

Latest comments (3)

Collapse
 
iamjaydev profile image
iamjaydev

Great post!

Collapse
 
cicirello profile image
Vincent A. Cicirello

Thank you

Collapse
 
cicirello profile image
Vincent A. Cicirello

I use this GitHub Action in several Java libraries that I maintain. If you'd like to see an example of actual output, you can visit the documentation of one of these libraries, and view the source of any of the javadoc pages. Here is a link direct to the module page for one of my Java libraries: chips-n-salsa.cicirello.org/api/or...

If you want to head straight to the source of that library's documentation site, see the gh-pages branch of its repository: github.com/cicirello/Chips-n-Salsa.... The javadoc generated documentation is then within the subdirectory api.