https://github.com/cicirello/javadoc-cleanup
Create mobile-friendly documentation sites by post-processing javadocs in GitHub Actions
Science Score: 26.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
○CITATION.cff file
-
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
○DOI references
-
○Academic publication links
-
○Committers with academic emails
-
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (10.7%) to scientific vocabulary
Keywords
Keywords from Contributors
Repository
Create mobile-friendly documentation sites by post-processing javadocs in GitHub Actions
Basic Info
- Host: GitHub
- Owner: cicirello
- License: mit
- Language: Python
- Default Branch: master
- Homepage: https://actions.cicirello.org/javadoc-cleanup/
- Size: 337 KB
Statistics
- Stars: 12
- Watchers: 1
- Forks: 2
- Open Issues: 1
- Releases: 14
Topics
Metadata Files
README.md
javadoc-cleanup
Check out all of our GitHub Actions: https://actions.cicirello.org/
About
| GitHub Actions | 
|
| :--- | :--- |
| Build Status |
|
| Source Info | 
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), where the timestamp
is not ommitted in the overview-summary.html generated by javadoc.
* It is also capable of generating and inserting the canonical URL for each page, of the
form <link rel="canonical" href="https://URL.TO.YOUR.API.DOC.WEBSITE/page.html">.
* 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 a referrer policy, or really
anything else that is valid in the head of an html file.
* 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 designed to be used in combination with other GitHub Actions. For example, it does not commit and push the modified javadocs. See the Example Workflows for examples of combining with other actions in your workflow. We also have links to a few projects that are actively using the javadoc-cleanup action in the section Examples in Other Projects.
Table of Contents
The remainder of the documentation is organized into the following sections: * Inputs: Documentation of all of the actions's inputs. * Outputs: Documentation of all of the actions's outputs. * Example Workflows: Example workflows illustrating various features. * Examples in Other Projects * Built With: A list of the tools, etc used to develop this action. * Blog Posts: A selection of blog posts about the GitHub Action. * Support the Project: Information on various ways that you can support the project.
Inputs
path-to-root
The path to the root of the website relative to the
root of the repository. The default is . which
is appropriate in cases where you are using a gh-pages branch
for your documentation site. If you are instead using this for a GitHub Pages site
in the docs directory, then
just pass docs for this input.
base-url-path
This is the url to the root of your website. If you provide this
input, then javadoc-cleanup will generate and insert a canonical
link for each page in the header, of the
form: <link rel="canonical" href="https://URL.TO.YOUR.API.DOC.WEBSITE/page.html">,
assuming base-url-path equals "https://URL.TO.YOUR.API.DOC.WEBSITE/" and
assuming page.html is the relevant filename.
user-defined-block
This input can be used if there is anything else that you want to insert into the head of every javadoc generated page. For example if you want to insert links to the site's favicon. Here are a couple examples.
Perhaps you have an favicon.svg in the images directory of the documentation site, then the following will insert a link to it in the head of every javadoc generated page:
yml
- name: Tidy up the javadocs
uses: cicirello/javadoc-cleanup@v1
with:
path-to-root: docs
user-defined-block: |
<link rel="icon" href="/images/favicon.svg" sizes="any" type="image/svg+xml">
In the above, the | is what YAML calls a block scalar, essentially a multiline string.
In the example above, the string itself is only a single line, however, the advantage
of using this syntax is to avoid the need to escape all of the quote characters.
Perhaps there are multiple lines you want to insert into the head of the pages. This next example shows this using a case where perhaps you have both svg and png versions of your favicon.
yml
- name: Tidy up the javadocs
uses: cicirello/javadoc-cleanup@v1
with:
path-to-root: docs
user-defined-block: |
<link rel="icon" href="/images/favicon.svg" sizes="any" type="image/svg+xml">
<link rel="icon" href="/images/favicon.png" type="image/png">
Please note that the action does not attempt to check the syntax of your user-defined-block.
It simply inserts it verbatim into the head of every javadoc generated page.
Outputs
modified-count
This output is the count of the number of html pages modified by the action.
Example Workflows
Prerequisites of Examples
- The example workflows assume that
javadocis run via Maven, and it also assumes that Maven's default directory structure is in use (e.g., that output is to atargetdirectory). You should put Maven'stargetdirectory in your.gitignore. The example workflows include a step that copies the generated documentation from Maven's default oftarget/site/apidocsto thedocsfolder (assuming you are serving the documentation via GitHub Pages in thedocsfolder). - Depending upon the version of Java, javadoc may generate multiple zip files
of its search index, in addition to the JavaScript versions of those very
search index files. This is true of javadoc for Java 11, although more recent Java
versions have eliminated the zip files. These zip files are completely unnecessary.
The documentation will use the
jsversions of these. Additionally, thezipfiles are problematic for documentation sites served from a git repository because they will appear as if they changed every time javadoc runs, even if nothing has actually changed (e.g., due to time-stamping). We strongly recommend that for these reasons you add the five zip files to your.gitignore. They aremodule-search-index.zip,package-search-index.zip,type-search-index.zip,member-search-index.zip, andtag-search-index.zip. They are functionally unnecessary, as the.jscounterparts alone are sufficient for javadoc's search to work.
Basic Syntax
You can run the action with a step in yuor workflow like this (assuming that your javadocs are in docs directory:
yml
- name: Tidy up the javadocs
uses: cicirello/javadoc-cleanup@v1
with:
path-to-root: docs
In the above example, the major release version was used, which ensures that you'll be using the latest patch level release, including any bug fixes, etc. If you prefer, you can also use a specific version such as with:
yml
- name: Tidy up the javadocs
uses: cicirello/javadoc-cleanup@v1.3.7
with:
path-to-root: docs
Example 1: Basic example without canonical links
This example workflow is triggered by a push of java source files.
After setting up java, Maven is used to generate the javadocs, and
the javadocs are then copied from Maven default target location to the
docs directory where the GitHub Pages documentation site is assumed hosted.
After which, the javadoc-cleanup action runs. The workflow then outputs
the number of modified html pages (for logging purposes). The
workflow then commits the changes (if any).
This example doesn't push the changes,
but you can easily add a git push after the commit, or add another action to handle
that.
```yml name: docs
on: push: branches: [ master ] paths: [ '**.java' ]
jobs: api-website: runs-on: ubuntu-latest steps: - name: Checkout the repo uses: actions/checkout@v4
- name: Set up the Java JDK
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'adopt'
- name: Build docs with Maven
run: mvn javadoc:javadoc
- name: Copy to Documentation Website Location
run: |
rm -rf docs
cp -rf target/site/apidocs/. docs
- name: Tidy up the javadocs
id: tidy
uses: cicirello/javadoc-cleanup@v1
with:
path-to-root: docs
- name: Log javadoc-cleanup output
run: |
echo "modified-count = ${{ steps.tidy.outputs.modified-count }}"
- name: Commit documentation changes
run: |
if [[ `git status --porcelain` ]]; then
git config --global user.name 'YOUR NAME HERE'
git config --global user.email 'YOUR-GITHUB-USERID@users.noreply.github.com'
git add -A
git commit -m "Automated API website updates."
fi
```
Example 2: Basic example with canonical links
This example workflow is mostly the same as above, except it also generates and inserts canonical links in each javadoc page.
```yml name: docs
on: push: branches: [ master ] paths: [ '**.java' ]
jobs: api-website: runs-on: ubuntu-latest steps: - name: Checkout the repo uses: actions/checkout@v4
- name: Set up the Java JDK
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'adopt'
- name: Build docs with Maven
run: mvn javadoc:javadoc
- name: Copy to Documentation Website Location
run: |
rm -rf docs
cp -rf target/site/apidocs/. docs
- name: Tidy up the javadocs
id: tidy
uses: cicirello/javadoc-cleanup@v1
with:
base-url-path: https://URL.FOR.YOUR.WEBSITE.GOES.HERE/
path-to-root: docs
- name: Log javadoc-cleanup output
run: |
echo "modified-count = ${{ steps.tidy.outputs.modified-count }}"
- name: Commit documentation changes
run: |
if [[ `git status --porcelain` ]]; then
git config --global user.name 'YOUR NAME HERE'
git config --global user.email 'YOUR-GITHUB-USERID@users.noreply.github.com'
git add -A
git commit -m "Automated API website updates."
fi
```
Example 3: Combining with other GitHub actions
This example combines the javadoc-cleanup action with other actions. Specifically,
it uses the cicirello/generate-sitemap action
to generate a sitemap for the documentation website, and the
peter-evans/create-pull-request
action to create a pull request with the changes. Note that for this example,
the checkout action is called with fetch-depth: 0 because generate-sitemap needs
the complete commit history. This is unnecessary for usage of the javadoc-cleanup action
alone.
```yml name: docs
on: push: branches: [ master ] paths: [ '**.java' ]
jobs: api-website: runs-on: ubuntu-latest steps: - name: Checkout the repo uses: actions/checkout@v4 with: fetch-depth: 0
- name: Set up the Java JDK
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'adopt'
- name: Build docs with Maven
run: mvn javadoc:javadoc
- name: Copy to Documentation Website Location
run: |
rm -rf docs
cp -rf target/site/apidocs/. docs
- name: Tidy up the javadocs
id: tidy
uses: cicirello/javadoc-cleanup@v1
with:
path-to-root: docs
base-url-path: https://URL.FOR.YOUR.WEBSITE.GOES.HERE/
- name: Log javadoc-cleanup output
run: |
echo "modified-count = ${{ steps.tidy.outputs.modified-count }}"
- name: Commit documentation changes
run: |
if [[ `git status --porcelain` ]]; then
git config --global user.name 'YOUR NAME HERE'
git config --global user.email 'YOUR-GITHUB-USERID@users.noreply.github.com'
git add -A
git commit -m "Automated API website updates."
fi
- name: Generate the sitemap
id: sitemap
uses: cicirello/generate-sitemap@v1
with:
base-url-path: https://URL.FOR.YOUR.WEBSITE.GOES.HERE/
path-to-root: docs
- name: Create Pull Request
uses: peter-evans/create-pull-request@v3.8.2
with:
title: "Automated API website updates."
commit-message: "Automated API documentation website updates."
```
Examples in Other Projects
If you would like to see examples where the action is actively used, here are a few repositories that
are actively using the javadoc-cleanup action. The table provides a link to repositories using the
action, and direct links to the relevant workflow as well as to the api documentation sites that result
from the workflow.
| Repository | Workflow | Javadocs | | :----- | :----- | :----- | | Chips-n-Salsa | docs.yml | https://chips-n-salsa.cicirello.org/api/ | | JavaPermutationTools | docs.yml | https://jpt.cicirello.org/api/ |
Built With
The javadoc-cleanup action uses the following:
* Python (implemented almost entirely in Python);
* The cicirello/pyaction Docker container, which
is designed to support GitHub Actions development in the Python language (see
pyaction's GitHub repository); and
* We started with our template repository for GitHub Actions implemented in
Python: cicirello/python-github-action-template.
Blog Posts
Here is a selection of blog posts about javadoc-cleanup on DEV.to: * Deploy a Documentation Website for a Java Library Using GitHub Actions, posted on DEV on November 30, 2022. * Post-Process Javadoc-Generated Documentation in GitHub Actions Before Deploying to the Web, posted on DEV on November 16, 2022.
Support the Project
You can support the project in a number of ways:
* Starring: If you find the javadoc-cleanup action
useful, consider starring the repository.
* Sharing with Others: Consider sharing it with others who
you feel might find it useful.
* Reporting Issues: If you find a bug or have a suggestion for
a new feature, please report it via
the Issue tracker.
* Contributing Code: If there is an open issue that you think
you can help with, submit a pull request.
* Sponsoring: You can also consider
becoming a sponsor.
License
The scripts and documentation for this GitHub action are released under the MIT License.
Owner
- Name: Vincent A. Cicirello
- Login: cicirello
- Kind: user
- Location: Galloway, NJ
- Company: Stockton University
- Website: https://www.cicirello.org/
- Repositories: 53
- Profile: https://github.com/cicirello
Vincent A. Cicirello is a researcher in AI, evolutionary computation, and swarm intelligence.
GitHub Events
Total
- Release event: 1
- Watch event: 2
- Delete event: 5
- Issue comment event: 2
- Push event: 7
- Pull request review event: 2
- Pull request event: 9
- Fork event: 1
- Create event: 4
Last Year
- Release event: 1
- Watch event: 2
- Delete event: 5
- Issue comment event: 2
- Push event: 7
- Pull request review event: 2
- Pull request event: 9
- Fork event: 1
- Create event: 4
Committers
Last synced: over 1 year ago
Top Committers
| Name | Commits | |
|---|---|---|
| Vincent A. Cicirello | c****o | 165 |
| dependabot[bot] | 4****] | 42 |
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 17
- Total pull requests: 76
- Average time to close issues: 1 day
- Average time to close pull requests: about 19 hours
- Total issue authors: 2
- Total pull request authors: 2
- Average comments per issue: 0.41
- Average comments per pull request: 0.07
- Merged pull requests: 72
- Bot issues: 0
- Bot pull requests: 51
Past Year
- Issues: 0
- Pull requests: 8
- Average time to close issues: N/A
- Average time to close pull requests: 3 days
- Issue authors: 0
- Pull request authors: 2
- Average comments per issue: 0
- Average comments per pull request: 0.25
- Merged pull requests: 6
- Bot issues: 0
- Bot pull requests: 7
Top Authors
Issue Authors
- cicirello (16)
- Retch (1)
Pull Request Authors
- dependabot[bot] (51)
- cicirello (25)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 1
- Total downloads: unknown
- Total dependent packages: 0
- Total dependent repositories: 11
- Total versions: 15
github actions: cicirello/javadoc-cleanup
Create mobile-friendly javadocs in GitHub Actions
- Homepage: https://actions.cicirello.org/javadoc-cleanup/
- License: mit
-
Latest release: v1.3.8
published 7 months ago
Rankings
Dependencies
- ./ * composite
- actions/checkout v3 composite
- actions/setup-python v4 composite
- actions/checkout v3 composite
- github/codeql-action/analyze v2 composite
- github/codeql-action/autobuild v2 composite
- github/codeql-action/init v2 composite
- actions/checkout v3 composite
- Dockerfile * docker
- ghcr.io/cicirello/pyaction 4.14.0 build