{"id":22515361,"url":"https://github.com/scijava/javadoc-wrangler","last_synced_at":"2025-03-28T02:19:27.050Z","repository":{"id":142923341,"uuid":"445661343","full_name":"scijava/javadoc-wrangler","owner":"scijava","description":"Content generator for javadoc.scijava.org","archived":false,"fork":false,"pushed_at":"2023-10-17T16:20:12.000Z","size":175,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-02-02T03:41:23.368Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://javadoc.scijava.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scijava.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-01-07T21:50:29.000Z","updated_at":"2022-01-07T21:51:56.000Z","dependencies_parsed_at":"2025-02-02T03:40:36.820Z","dependency_job_id":"b3f92538-8db5-4c18-a31c-2ffadf57de74","html_url":"https://github.com/scijava/javadoc-wrangler","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scijava%2Fjavadoc-wrangler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scijava%2Fjavadoc-wrangler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scijava%2Fjavadoc-wrangler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scijava%2Fjavadoc-wrangler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scijava","download_url":"https://codeload.github.com/scijava/javadoc-wrangler/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245955328,"owners_count":20699891,"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":[],"created_at":"2024-12-07T03:30:10.317Z","updated_at":"2025-03-28T02:19:26.482Z","avatar_url":"https://github.com/scijava.png","language":"Python","readme":"This repository houses the logic for generating\nthe javadoc content served from javadoc.scijava.org.\n\n## TL;DR: What is generated\n\n1. **Actual javadoc for each component.**\n   E.g. `/org.scijava/scijava-common/2.87.1/`. Analogous to javadoc.io,\n   but also supports artifacts deployed to maven.scijava.org. And javadoc\n   of supported components is unpacked in advance, not on the fly on demand.\n\n2. **Unioned index of all managed components for a particular BOM.**\n   E.g. `/org.scijava/pom-scijava/31.1.0/`. Useful for passing as a link to the\n   `javadoc` tool, or when you want to access the javadoc for a library\n   corresponding to a particular BOM version. Actual class and package javadoc\n   is referenced via 301 redirects to the correct component. For example, the\n   path:\n   ```\n   /org.scijava/pom-scijava/31.1.0/net/imglib2/img/Img.html\n   ```\n   redirects to:\n   ```\n   /net.imglib2/imglib2/5.12.0/net/imglib2/img/Img.html\n   ```\n   Because the `net.imglib2.img.Img` class is part of\n   `net.imglib2:imglib2:5.12.0`, one of the BOM's managed components.\n\n3. **Toplevel index of available javadoc.**\n\n## Background and rationale\n\nThe generated content is designed around the idea of a [Bill of Materials]\n(BOM), which provides a list of *managed* components at particular versions\nthat are tested and working together. By importing the BOM into your build, you\ncan then depend on any combination of the managed components without explicitly\ndeclaring their versions, and the versions will be inferred from the BOM.\n\nNow suppose you are developing a Java library L that depends on several managed\ncomponents: A, B, C, D, etc. One of the steps when building L is to generate\nits [javadoc], package it into a JAR file with classifier `javadoc`, and deploy\nthe resulting `L-x.y.z-javadoc.jar` artifact to a remote Maven repository.\n\nThese javadoc artifacts are useful for [IDEs] to browse javadoc on demand from\nwithin the user interface. But there are two major drawbacks:\n\n1. Humans cannot read the javadoc directly in a web browser.\n\n2. The [`javadoc` tool] cannot consume them as links when generating\n   downstream javadoc, so your library L will not have hyperlinks to\n   classes from dependencies A, B, C, D, etc.\n\nFor projects deployed to [Maven Central], one solution is [javadoc.io], which\noffers on-demand browsing of any project that publishes javadoc classifier\nartifacts as described above. Links to javadoc.io-hosted javadoc\n(e.g. [SciJava Common v2.87.1]) can be passed to the `javadoc` tool as links,\nand the javadoc for your library L will then have hyperlinks to the classes\nof dependencies A, B, C, D, etc., for which javadoc.io links were provided.\n\nThere are still challenges, however:\n\n* For each link given to the `javadoc` tool, its `element-list` (`package-list`\n  in older versions of Java) index must be fetched. Unfortunately, this step is\n  slow, scaling linearly by the number of links given. For projects with many\n  dependencies, each with its own javadoc.io link, this can bloat javadoc\n  generation time by many minutes. In an empirical test, building javadoc for a\n  small project with no links took 11 seconds, with 37 links took 48 seconds,\n  and with 231 links took 215 seconds.\n\n* The javadoc.io service does not support javadoc artifacts published to Maven\n  repositories other than Maven Central. So projects published to\n  maven.scijava.org, for example, cannot be browsed there. And as far as I\n  know, the server-side javadoc.io code is not open source, so configuring\n  javadoc.scijava.org to work analogously, but for maven.scijava.org instead of\n  Maven Central, requires coding our own solution (i.e., this repository).\n\n## How this repository helps\n\nThe `wrangle.py` script generates a **combined javadoc target for a BOM**,\nunioning the `element-list`/`package-list` index so that it can be passed to\nthe `javadoc` tool as a single link target, resulting in fast javadoc build\ntimes, with permanent reproducible links embedded in the resultant javadoc.\n\nThe script also unpacks the **actual javadoc for each managed component**.\n\nThe combined javadoc target, rather than recapitulating the HTML for every\nclass of every component, instead uses 301 redirects via an Apache `.htaccess`\nfile, which point at the unmodified unpacked javadoc for that component.\n\nThis approach has several advantages:\n\n* The `javadoc` tool has a single reproducible link target, so new javadoc\n  builds more quickly, with classes from dependencies linked with permalinks.\n\n* Every available javadoc for every component managed by every version of\n  pom-scijava is accessible from a canonical location, with stable links.\n\n* Old javadoc using version-agnostic (and therefore irreproducible) links\n  is adjusted during unpacking to use stable links instead\u0026mdash;e.g.,\n  `/SciJava/org/scijava/Context.html` \u0026rarr;\n  `/org.scijava/pom-scijava/30.0.0/org/scijava/Context.html` which then\n  redirects to `org.scijava/scijava-common/2.85.0/org/scijava/Context.html`.\n\n  The various version-agnostic prefixes from the prior incarnation of the\n  javadoc.scijava.org website now redirect to the latest pom-scijava javadoc\n  prefix\u0026mdash;e.g., `/SciJava/` \u0026rarr; `/org.scijava/pom-scijava/latest/`\n  \u0026rarr; `org.scijava/pom-scijava/31.1.0`, with the `latest` path updating\n  over time to always redirect to the newest BOM version hosted on the site.\n\n------------------------------------------------------------------------\n\n[Bill of Materials]:      https://imagej.net/BOM\n[IDEs]:                   https://en.wikipedia.org/wiki/Integrated_Development_Environment\n[javadoc.io]:             https://javadoc.io/\n[javadoc]:                https://en.wikipedia.org/wiki/Javadoc\n[`javadoc` tool]:         https://openjdk.java.net/groups/compiler/javadoc-architecture.html\n[Maven Central]:          https://search.maven.org/\n[SciJava Common v2.87.1]: https://javadoc.io/doc/org.scijava/scijava-common/2.87.1/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscijava%2Fjavadoc-wrangler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscijava%2Fjavadoc-wrangler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscijava%2Fjavadoc-wrangler/lists"}