如何将项目的 Java Doc 发布到 github？

Posted 2023-03-06

【中文标题】如何将项目的 Java Doc 发布到 github？

【英文标题】：How to release a Java Doc of a Project to github?

【发布时间】：2019-10-21 21:33:25

【问题描述】：

我想在 Github 上发布一个项目。 它可以工作，我可以通过 Gradle 将其作为依赖项检索。 但是没有 JavaDoc。

留言：

注意：该元素既没有附加源代码也没有附加 Javadoc，因此找不到 Javadoc。

我需要构建一个 JAR 吗？或者有什么方法可以将我的 JavaDoc 添加到项目中，以便使用 gradle 构建 JavaDoc 时可用？

【问题讨论】：

通常您会将您的文档作为单独的 jar 文件发送。和/或作为网站在线提供（例如通过 github.io）。然后，用户可以简单地告诉他的 IDE 从哪里获取文档（例如网页或 jar）。

【参考方案1】：

不要将 JavaDoc 发布到 (a) Github（存储库），因为 JavaDoc 是 Java 源代码的派生产品。

我们想一想，当您更改 JavaDocs 中的注释时，您的 JavaDocs Github 存储库也需要更改。这是冗余。

让我们看看 Github 上一些知名的 Java 项目，例如 https://github.com/spring-projects/spring-boot，它们不会将任何 JavaDoc（html 文件）放在 GitHub 存储库中。

通过 Gradle 生成 JavaDocs 的任务：https://docs.gradle.org/current/dsl/org.gradle.api.tasks.javadoc.Javadoc.html

【讨论】：

您能否提出一个替代方案来分发它？例如在下载部分或作为网站上的jar，例如使用github.io?也许像你已经做的那样支持一些示例项目。

让我们看看***.com/a/45998252/3728901，然后，将JavaDoc HTML文件放到Web服务器上的一个目录中。

@DoNhuVy 使用 Gradle 构建时会生成必要的 JavaDocs 吗？这样它们就可以作为依赖项使用？

Gradle 是一个构建，而不是依赖，你不需要更多的依赖。

@DoNhuVy 我用 Gradle 生成了 JavaDoc。这很好用。我重新发布了我的小项目，并将依赖项放在 othery gradle build 中。一切正常。文档除外。即使我运行“gradle javadoc”任务。 “我的”依赖项中没有任何记录。顺便说一句，这是一个标准构建。没有特殊的文件结构或类似的东西。

【参考方案2】：

您可以use the docs/ folder or the gh-pages branch在 GitHub 上发布您生成的 JavaDoc。

示例：ebourg.github.io/jsign/apidocs/ 来自 github.com/ebourg/jsign/tree/gh-pages。

另一种方法是将您的可交付成果（jar 和 javadoc.jar）发布到二进制引用（Central Maven 或 Bintray），并让第三方服务为您公开 Javadoc。 见“www.javadoc.io”