cicirello/javadoc-cleanup

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

Vincent A Cicirello

	Sites where you can find me or my work
Web and social media
Software development
Publications

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

javadoc-cleanup's Issues

BUG: the new `GITHUB_OUTPUT` may not exist on all self-hosted runners

Summary

Some users may be using the action on a self-hosted runner not yet updated to a version supporting the new GitHub Actions GITHUB_OUTPUT environment file. The update for the deprecated set-output workflow command may have broken the action for those users, depending on whether they are relying on the workflow outputs from the action.

Enable CodeQL code scanning on push and pull-requests

Update dependabot configuration to update master rather than development

Javadoc pages with redirects should be noindexed

Describe the bug
For recent Java versions, definitely 17 and probably earlier, javadoc generates an index.html at top level in the docs that redirects to the javadoc page for the module for projects that use Java Platform Module System. And in other cases redirects to javadoc page for a package. In both of those cases, the page with the redirect should have a noindex directive. It does not. This is technically a bug in javadoc. For javadoc documentation hosted online, the lack of a noindex directive in a page that redirects is problematic with search engines such as Google. It would be desirable if javadoc-cleanup can fix it, rather than waiting for javadoc itself to handle this, especially since they are unlikely to back port any fix to existing versions.

To Reproduce
Steps to reproduce the behavior:

1. Generate javadocs for a Java 17 project with JPMS module.
2. Run javadoc-cleanup.
3. Inspect source of top level index.html.
4. Observe that it includes a redirect but doesn't direct search engines to noindex.

Expected behavior
Insert a noindex directive in any javadoc pages that include redirects.

Relevant System Info (please complete the following information):

• OS
• Version
• etc

Additional context

• Java 17
• project with a JPMS module

Works great

It is working very good, but it would be interesting to see whether the "splitindex" javadoc parameter would work, i couldn't get it running with the parameter.

Bug in regex used to detect if an HTML page was generated in Javadoc

Summary

Bug in regex used to detect if an HTML page was generated in Javadoc. Specifically, \s+ in string passed to Python's compile function is being interpreted as an attempt to use an escape \s in the string, rather than passing it along to Python's regex processor as a regex escape.

Bug in regex used to detect if an html file is a redirect

Summary

Fix bug in regex used to detect if an html file is a redirect. Specifically, \s+ in string passed to Python's compile function is being interpreted as an attempt to use an escape \s in the string, rather than passing it along to Python's regex processor as a regex escape. And likewise for \..

Viewport already set by javadoc in Java 16+

Describe the bug
With Java 16+, javadoc now sets the viewport appropriately. The javadoc-cleanup action will then add a redundant viewport declaration.

To Reproduce
Steps to reproduce the behavior:

1. Generate javadoc with Java 16 or later.
2. View source.
3. Observe that the viewport declaration already exists.

Expected behavior
No addition of a redundant meta viewport declaration.

Bug in regex used to detect if a Javadoc page already specifies a viewport directive

Summary

Fix bug in regex used to detect if a Javadoc page already specifies a viewport directive, such as in Java 16+. Specifically, \s+ in string passed to Python's compile function is being interpreted as an attempt to use an escape \s in the string, rather than passing it along to Python's regex processor as a regex escape.

Generated by javadoc comment format changed Java 16+

Describe the bug
The comment indicating that the html file was generated by javadoc has a new format beginning with Java 16+. Previously, that comment simply indicates that it was generated by javadoc. It now includes the Java version number. This has potential to impact javadoc-cleanup's removal of any stray timestamps, although it is also possible that the bug in javadoc that resulted in stray timestamps even if flag used to suppress may have been resolved. Verify that this still works with new javadoc format. Fix if necessary.

Ability to insert link to site's favicon

Describe the solution you'd like
The ability to insert a link to a site's favicon into the head of each javadoc page. If the site's favicon is in the root and named favicon.ico then this is not needed. But for favicons named differently, or located in a different directory than the root, or of a file type other than ico, a link is needed from each page for browsers to recognize it. For example, along the lines of <link rel="icon" href="/images/favicon.svg" sizes="any" type="image/svg+xml">. This will require new inputs to control whether or not to insert favicon links, as well as to get the path to the favicon, the type, sizes, etc.

Add a changelog to the repo

Add integration tests

The project currently has a set of unit tests that run on all pushes and pull requests, unit testing the various Python functions. However, thus far, integration testing of the action itself has been done manually by running the action via the master branch from the repo of another project that uses this GitHub Action, prior to each new release to the Marketplace.

A proper integration test should be implemented, and then integrated into the build workflow.

Update example workflows to reflect latest release of setup-java action

The actions/setup-java action's latest release added new inputs. Since all foreseeable usage of javadoc-cleanup will also involve that action, important to keep example workflows up to date relative to it.

Replace usage of GitHub Action's deprecated set-output command

Describe the bug
GitHub Actions has deprecated the set-output workflow command, which we are currently using for workflow outputs of the action. See https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/. That same link indicates the replacement.

To Reproduce
Steps to reproduce the behavior:

1. Run the action.
2. Inspect the workflow run.
3. Notice the deprecation warning.

Expected behavior
No deprecation warning.

Bump Python to 3.12 in CI/CD workflows

Summary

Bump Python to 3.12 in CI/CD workflows, specifically when running unit tests.

Redundant canonical url in root level index.html for recent Java versions

Describe the bug
For recent Java versions, definitely 17 and probably earlier, javadoc generates an index.html at top level in the docs that redirects to the javadoc page for the module for projects that use Java Platform Module System. And in other cases redirects to javadoc page for a package. In both of those cases, the page with the redirect has a canonical url correctly referencing the page it redirects to. However, the javadoc-cleanup action then inserts a redundant canonical url in that page, but with the page that redirects as the canonical url.

To Reproduce
Steps to reproduce the behavior:

1. Generate javadocs for a Java 17 project with JPMS module.
2. Run javadoc-cleanup.
3. Inspect source of top level index.html.
4. Observe the correct canonical inserted by javadoc and the redundant incorrect one inserted by javadoc-cleanup.

Expected behavior
Don't insert canonical url if one is already present.

Relevant System Info (please complete the following information):

• Java 17
• project with a JPMS module

Change docs to recommend gitignoring javadoc's index zip files

javadoc (as of Java 11) generates several zip files that are compressed versions of the search indexes. The javadoc search functionality works without them (serving the uncompressed versions), and they are really redundant as web servers should likely compress these for transit. Later versions of Java have eliminated these zip files altogether. We could add functionality to javadoc-cleanup to delete them if present, but cleaner for user of the action to gitignore them.