{"id":15684020,"url":"https://github.com/cicirello/javadoc-cleanup","last_synced_at":"2025-05-07T02:41:04.123Z","repository":{"id":38079620,"uuid":"297662914","full_name":"cicirello/javadoc-cleanup","owner":"cicirello","description":"Create mobile-friendly documentation sites by post-processing javadocs in GitHub Actions","archived":false,"fork":false,"pushed_at":"2024-09-27T19:17:23.000Z","size":380,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-12T10:01:59.175Z","etag":null,"topics":["documentation","documentation-site","github-actions","java","javadoc","mobile-browsers","mobile-friendly"],"latest_commit_sha":null,"homepage":"https://actions.cicirello.org/javadoc-cleanup/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cicirello.png","metadata":{"funding":{"github":"cicirello","patreon":null,"open_collective":null,"ko_fi":"cicirello","tidelift":null,"community_bridge":null,"liberapay":"cicirello","issuehunt":null,"otechie":null,"custom":null},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-22T13:47:20.000Z","updated_at":"2024-12-11T11:34:54.000Z","dependencies_parsed_at":"2023-02-04T19:47:13.099Z","dependency_job_id":"a07f595b-b1e0-493f-bb4f-12522dc64bff","html_url":"https://github.com/cicirello/javadoc-cleanup","commit_stats":{"total_commits":207,"total_committers":2,"mean_commits":103.5,"dds":0.2028985507246377,"last_synced_commit":"5ee388df5a09b2e0d11f5b6dbc63c3fbcd2f3e3b"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fjavadoc-cleanup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fjavadoc-cleanup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fjavadoc-cleanup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cicirello%2Fjavadoc-cleanup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cicirello","download_url":"https://codeload.github.com/cicirello/javadoc-cleanup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252802439,"owners_count":21806502,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","documentation-site","github-actions","java","javadoc","mobile-browsers","mobile-friendly"],"created_at":"2024-10-03T17:09:43.710Z","updated_at":"2025-05-07T02:41:04.100Z","avatar_url":"https://github.com/cicirello.png","language":"Python","funding_links":["https://github.com/sponsors/cicirello","https://ko-fi.com/cicirello","https://liberapay.com/cicirello"],"categories":[],"sub_categories":[],"readme":"# javadoc-cleanup\n\n[![cicirello/javadoc-cleanup - Create mobile-friendly documentation sites by post-processing javadocs in GitHub Actions](https://actions.cicirello.org/images/javadoc-cleanup640.png)](#javadoc-cleanup)\n\nCheck out all of our GitHub Actions: https://actions.cicirello.org/\n\n## About\n\n| __GitHub Actions__ | [![GitHub release (latest by date)](https://img.shields.io/github/v/release/cicirello/javadoc-cleanup?label=Marketplace\u0026logo=GitHub)](https://github.com/marketplace/actions/javadoc-cleanup) [![Count of Action Users](https://badgen.net/github/dependents-repo/cicirello/javadoc-cleanup?icon=github\u0026label=used%20by)](https://github.com/cicirello/javadoc-cleanup/network/dependents) |\n| :--- | :--- |\n| __Build Status__ | [![build](https://github.com/cicirello/javadoc-cleanup/actions/workflows/build.yml/badge.svg)](https://github.com/cicirello/javadoc-cleanup/actions/workflows/build.yml) [![CodeQL](https://github.com/cicirello/javadoc-cleanup/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/cicirello/javadoc-cleanup/actions/workflows/codeql-analysis.yml) |\n| __Source Info__ | [![License](https://img.shields.io/github/license/cicirello/javadoc-cleanup)](https://github.com/cicirello/javadoc-cleanup/blob/master/LICENSE) [![GitHub top language](https://img.shields.io/github/languages/top/cicirello/javadoc-cleanup)](https://github.com/cicirello/javadoc-cleanup) |\n| __Support__ | [![GitHub Sponsors](https://img.shields.io/badge/sponsor-30363D?logo=GitHub-Sponsors\u0026logoColor=#EA4AAA)](https://github.com/sponsors/cicirello) [![Liberapay](https://img.shields.io/badge/Liberapay-F6C915?logo=liberapay\u0026logoColor=black)](https://liberapay.com/cicirello) [![Ko-Fi](https://img.shields.io/badge/Ko--fi-F16061?logo=ko-fi\u0026logoColor=white)](https://ko-fi.com/cicirello) |\n\nThe javadoc-cleanup GitHub action is a utility to tidy up javadocs prior to deployment to \nan API documentation website, assumed hosted on GitHub Pages. It performs the following\nfunctions:\n* Improves mobile browsing experience: It \n  inserts `\u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1\"\u003e` within the `\u003chead\u003e` of \n  each html file that was generated by javadoc, if not already present. Beginning with Java 16, javadoc \n  properly defines the viewport, whereas prior to Java 16, it does not.\n* Strips out any timestamps inserted by javadoc: The timestamps cause a variety of version control \n  issues for documentation sites maintained in git repositories. Javadoc has an option `-notimestamp` to \n  direct javadoc not to insert timestamps (which we recommend that you also use). However, at the present \n  time there appears to be a bug (in OpenJDK 11's javadoc, and possibly other versions), where the timestamp \n  is not ommitted in the `overview-summary.html` generated by javadoc.\n* It is also capable of generating and inserting the canonical URL for each page, of the \n  form `\u003clink rel=\"canonical\" href=\"https://URL.TO.YOUR.API.DOC.WEBSITE/page.html\"\u003e`.\n* Enables inserting a user-defined block into the head of each javadoc generated \n  page. For example, if you want to insert a link to your site's favicon, or a referrer policy, or really \n  anything else that is valid in the head of an html file.\n* In projects that use the Java Platform Module System (JPMS), javadoc redirects the root `index.html` to\n  the page of a module, and under certain other circumstances to a package page. Such redirected pages\n  should direct search engines to `noindex`, but javadoc doesn't do so. The javadoc-cleanup action \n  inserts a `noindex, follow` directive in any such redirected pages.\n\nThe javadoc-cleanup GitHub action is designed to be used \nin combination with other GitHub Actions. For example, it \ndoes not commit and push the modified javadocs. See \nthe [Example Workflows](#example-workflows) for examples of combining\nwith other actions in your workflow. We also have links to a few projects\nthat are actively using the javadoc-cleanup action in the \nsection [Examples in Other Projects](#examples-in-other-projects).\n\n## Table of Contents\n\nThe remainder of the documentation is organized into the following\nsections:\n* [Inputs](#inputs): Documentation of all of the actions's inputs.\n* [Outputs](#outputs): Documentation of all of the actions's outputs.\n* [Example Workflows](#example-workflows): Example workflows illustrating various features.\n* [Examples in Other Projects](#examples-in-other-projects)\n* [Built With](#built-with): A list of the tools, etc used to develop this action.\n* [Blog Posts](#blog-posts): A selection of blog posts about the GitHub Action.\n* [Support the Project](#support-the-project): Information on various ways that you can support\n  the project.\n\n## Inputs\n\n### `path-to-root`\n\nThe path to the root of the website relative to the\nroot of the repository. The default is `.` which \nis appropriate in cases where you are using a `gh-pages` branch\nfor your documentation site. If you are instead using this for a GitHub Pages site\nin the `docs` directory, then\njust pass `docs` for this input.\n\n### `base-url-path`\n\nThis is the url to the root of your website. If you provide this \ninput, then javadoc-cleanup will generate and insert a canonical \nlink for each page in the header, of the \nform: `\u003clink rel=\"canonical\" href=\"https://URL.TO.YOUR.API.DOC.WEBSITE/page.html\"\u003e`, \nassuming `base-url-path` equals `\"https://URL.TO.YOUR.API.DOC.WEBSITE/\"` and \nassuming `page.html` is the relevant filename.\n\n### `user-defined-block`\n\nThis input can be used if there is anything else that you want to insert into\nthe head of every javadoc generated page. For example if you want to insert links\nto the site's favicon. Here are a couple examples.\n\nPerhaps you have an favicon.svg in the images directory of the documentation site,\nthen the following will insert a link to it in the head of every javadoc generated page:\n\n```yml\n    - name: Tidy up the javadocs\n      uses: cicirello/javadoc-cleanup@v1\n      with:\n        path-to-root: docs\n        user-defined-block: |\n          \u003clink rel=\"icon\" href=\"/images/favicon.svg\" sizes=\"any\" type=\"image/svg+xml\"\u003e\n```\n\nIn the above, the `|` is what YAML calls a block scalar, essentially a multiline string.\nIn the example above, the string itself is only a single line, however, the advantage\nof using this syntax is to avoid the need to escape all of the quote characters.\n\nPerhaps there are multiple lines you want to insert into the head of the pages. This next example\nshows this using a case where perhaps you have both svg and png versions of your favicon.\n\n```yml\n    - name: Tidy up the javadocs\n      uses: cicirello/javadoc-cleanup@v1\n      with:\n        path-to-root: docs\n        user-defined-block: |\n          \u003clink rel=\"icon\" href=\"/images/favicon.svg\" sizes=\"any\" type=\"image/svg+xml\"\u003e\n          \u003clink rel=\"icon\" href=\"/images/favicon.png\" type=\"image/png\"\u003e\n```\n\nPlease note that the action does not attempt to check the syntax of your `user-defined-block`.\nIt simply inserts it verbatim into the head of every javadoc generated page.\n\n## Outputs\n\n### `modified-count`\n\nThis output is the count of the number of html pages modified by the action.\n\n## Example Workflows\n\n### Prerequisites of Examples\n\n* The example workflows assume that `javadoc` is run via Maven, and it also\n  assumes that Maven's default directory structure is in use (e.g., that \n  output is to a `target` directory). You should put Maven's `target` directory\n  in your `.gitignore`. The example workflows include a step that copies the\n  generated documentation from Maven's default of `target/site/apidocs` to \n  the `docs` folder (assuming you are serving the documentation via GitHub Pages\n  in the `docs` folder).\n* Depending upon the version of Java, javadoc may generate multiple zip files\n  of its search index, in addition to the JavaScript versions of those very\n  search index files. This is true of javadoc for Java 11, although more recent Java\n  versions have eliminated the zip files. These zip files are completely unnecessary.\n  The documentation will use the `js` versions of these. Additionally, the\n  `zip` files are problematic for documentation sites served from a git repository\n  because they will appear as if they changed every time javadoc runs, even if\n  nothing has actually changed (e.g., due to time-stamping). We strongly recommend \n  that for these reasons you add the five zip files to your `.gitignore`.  They are\n  `module-search-index.zip`, `package-search-index.zip`, `type-search-index.zip`, \n  `member-search-index.zip`, and `tag-search-index.zip`. They are functionally \n  unnecessary, as the `.js` counterparts alone are sufficient for javadoc's search to\n  work.\n\n### Basic Syntax\n\nYou can run the action with a step in yuor workflow like this (assuming that your javadocs \nare in docs directory:\n\n```yml\n    - name: Tidy up the javadocs\n      uses: cicirello/javadoc-cleanup@v1\n      with:\n        path-to-root: docs\n```\n\nIn the above example, the major release version was used, which ensures that you'll\nbe using the latest patch level release, including any bug fixes, etc. If you prefer,\nyou can also use a specific version such as with:\n\n```yml\n    - name: Tidy up the javadocs\n      uses: cicirello/javadoc-cleanup@v1.3.7\n      with:\n        path-to-root: docs\n```\n\n\n### Example 1: Basic example without canonical links\n\nThis example workflow is triggered by a push of java source files.\nAfter setting up java, Maven is used to generate the javadocs, and \nthe javadocs are then copied from Maven default target location to the \ndocs directory where the GitHub Pages documentation site is assumed hosted. \nAfter which, the javadoc-cleanup action runs. The workflow then outputs \nthe number of modified html pages (for logging purposes). The \nworkflow then commits the changes (if any).\nThis example doesn't push the changes,\nbut you can easily add a `git push` after the commit, or add another action to handle\nthat.\n\n```yml\nname: docs\n\non:\n  push:\n    branches: [ master ]\n    paths: [ '**.java' ]\n\njobs:\n  api-website:\n    runs-on: ubuntu-latest\n    steps:\n    - name: Checkout the repo\n      uses: actions/checkout@v4\n\n    - name: Set up the Java JDK\n      uses: actions/setup-java@v3\n      with:\n        java-version: '17'\n        distribution: 'adopt'\n\n    - name: Build docs with Maven\n      run: mvn javadoc:javadoc\n\n    - name: Copy to Documentation Website Location\n      run: |\n        rm -rf docs\n        cp -rf target/site/apidocs/. docs\n\n    - name: Tidy up the javadocs\n      id: tidy\n      uses: cicirello/javadoc-cleanup@v1\n      with:\n        path-to-root: docs\n    \n    - name: Log javadoc-cleanup output\n      run: |\n        echo \"modified-count = ${{ steps.tidy.outputs.modified-count }}\"\n    \n    - name: Commit documentation changes\n      run: |\n        if [[ `git status --porcelain` ]]; then\n          git config --global user.name 'YOUR NAME HERE'\n          git config --global user.email 'YOUR-GITHUB-USERID@users.noreply.github.com'\n          git add -A\n          git commit -m \"Automated API website updates.\"\n        fi\n```\n\n### Example 2: Basic example with canonical links\n\nThis example workflow is mostly the same as above, except it also \ngenerates and inserts canonical links in each javadoc page.\n\n```yml\nname: docs\n\non:\n  push:\n    branches: [ master ]\n    paths: [ '**.java' ]\n\njobs:\n  api-website:\n    runs-on: ubuntu-latest\n    steps:\n    - name: Checkout the repo\n      uses: actions/checkout@v4\n\n    - name: Set up the Java JDK\n      uses: actions/setup-java@v3\n      with:\n        java-version: '17'\n        distribution: 'adopt'\n\n    - name: Build docs with Maven\n      run: mvn javadoc:javadoc\n\n    - name: Copy to Documentation Website Location\n      run: |\n        rm -rf docs\n        cp -rf target/site/apidocs/. docs\n\n    - name: Tidy up the javadocs\n      id: tidy\n      uses: cicirello/javadoc-cleanup@v1\n      with:\n        base-url-path: https://URL.FOR.YOUR.WEBSITE.GOES.HERE/\n        path-to-root: docs\n    \n    - name: Log javadoc-cleanup output\n      run: |\n        echo \"modified-count = ${{ steps.tidy.outputs.modified-count }}\"\n    \n    - name: Commit documentation changes\n      run: |\n        if [[ `git status --porcelain` ]]; then\n          git config --global user.name 'YOUR NAME HERE'\n          git config --global user.email 'YOUR-GITHUB-USERID@users.noreply.github.com'\n          git add -A\n          git commit -m \"Automated API website updates.\"\n        fi\n```\n\n\n### Example 3: Combining with other GitHub actions\n\nThis example combines the `javadoc-cleanup` action with other actions. Specifically,\nit uses the [cicirello/generate-sitemap](https://github.com/cicirello/generate-sitemap) action \nto generate a sitemap for the documentation website, and the \n[peter-evans/create-pull-request](https://github.com/peter-evans/create-pull-request)\naction to create a pull request with the changes.  Note that for this example,\nthe checkout action is called with `fetch-depth: 0` because `generate-sitemap` needs\nthe complete commit history. This is unnecessary for usage of the `javadoc-cleanup` action\nalone.\n\n```yml\nname: docs\n\non:\n  push:\n    branches: [ master ]\n    paths: [ '**.java' ]\n\njobs:\n  api-website:\n    runs-on: ubuntu-latest\n    steps:\n    - name: Checkout the repo\n      uses: actions/checkout@v4\n      with:\n        fetch-depth: 0 \n\n    - name: Set up the Java JDK\n      uses: actions/setup-java@v3\n      with:\n        java-version: '17'\n        distribution: 'adopt'\n    \n    - name: Build docs with Maven\n      run: mvn javadoc:javadoc\n\n    - name: Copy to Documentation Website Location\n      run: |\n        rm -rf docs\n        cp -rf target/site/apidocs/. docs\n    \n    - name: Tidy up the javadocs\n      id: tidy\n      uses: cicirello/javadoc-cleanup@v1\n      with:\n        path-to-root: docs\n        base-url-path: https://URL.FOR.YOUR.WEBSITE.GOES.HERE/\n    \n    - name: Log javadoc-cleanup output\n      run: |\n        echo \"modified-count = ${{ steps.tidy.outputs.modified-count }}\"\n    \n    - name: Commit documentation changes\n      run: |\n        if [[ `git status --porcelain` ]]; then\n          git config --global user.name 'YOUR NAME HERE'\n          git config --global user.email 'YOUR-GITHUB-USERID@users.noreply.github.com'\n          git add -A\n          git commit -m \"Automated API website updates.\"\n        fi\n\n    - name: Generate the sitemap\n      id: sitemap\n      uses: cicirello/generate-sitemap@v1\n      with:\n        base-url-path: https://URL.FOR.YOUR.WEBSITE.GOES.HERE/\n        path-to-root: docs\n        \n    - name: Create Pull Request\n      uses: peter-evans/create-pull-request@v3.8.2\n      with:\n        title: \"Automated API website updates.\"\n        commit-message: \"Automated API documentation website updates.\"\n```\n\n## Examples in Other Projects\n\nIf you would like to see examples where the action is actively used, here are a few repositories that \nare actively using the `javadoc-cleanup` action. The table provides a link to repositories using the \naction, and direct links to the relevant workflow as well as to the api documentation sites that result\nfrom the workflow.\n\n| Repository | Workflow | Javadocs |\n| :----- | :----- | :----- |\n| [Chips-n-Salsa](https://github.com/cicirello/Chips-n-Salsa) | [docs.yml](https://github.com/cicirello/Chips-n-Salsa/blob/master/.github/workflows/docs.yml) | https://chips-n-salsa.cicirello.org/api/ |\n| [JavaPermutationTools](https://github.com/cicirello/JavaPermutationTools) | [docs.yml](https://github.com/cicirello/JavaPermutationTools/blob/master/.github/workflows/docs.yml) | https://jpt.cicirello.org/api/ |\n\n## Built With\n\nThe `javadoc-cleanup` action uses the following:\n* Python (implemented almost entirely in Python);\n* The [cicirello/pyaction](https://actions.cicirello.org/pyaction/) Docker container, which \n  is designed to support GitHub Actions development in the Python language (see\n  [pyaction's GitHub repository](https://github.com/cicirello/pyaction)); and\n* We started with our template repository for GitHub Actions implemented in \n  Python: [cicirello/python-github-action-template](https://github.com/cicirello/python-github-action-template).\n  \n## Blog Posts\n\nHere is a selection of blog posts about javadoc-cleanup on DEV.to:\n* [Deploy a Documentation Website for a Java Library Using GitHub Actions](https://dev.to/cicirello/deploy-a-documentation-website-for-a-java-library-using-github-actions-197n), posted on DEV on November 30, 2022.\n* [Post-Process Javadoc-Generated Documentation in GitHub Actions Before Deploying to the Web](https://dev.to/cicirello/post-process-javadoc-generated-documentation-in-github-actions-before-deploying-to-the-web-11k8), posted on DEV on November 16, 2022.\n\n## Support the Project\n\nYou can support the project in a number of ways:\n* __Starring__: If you find the `javadoc-cleanup` action \n  useful, consider starring the repository.\n* __Sharing with Others__: Consider sharing it with others who\n  you feel might find it useful.\n* __Reporting Issues__: If you find a bug or have a suggestion for\n  a new feature, please report it via \n  the [Issue tracker](https://github.com/cicirello/javadoc-cleanup/issues).\n* __Contributing Code__: If there is an open issue that you think\n  you can help with, submit a pull request.\n* __Sponsoring__: You can also consider \n  [becoming a sponsor](https://github.com/sponsors/cicirello).\n\n## License\n\nThe scripts and documentation for this GitHub action are released under\nthe [MIT License](https://github.com/cicirello/javadoc-cleanup/blob/master/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fjavadoc-cleanup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcicirello%2Fjavadoc-cleanup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcicirello%2Fjavadoc-cleanup/lists"}