45

我正在寻找一种将javadocs从我的开源项目（在Eclipse中生成）转换为GitHub MarkDown的方法，或者想出一些其他简单的解决方案来在 GitHub 上显示我的文档（简单地添加一个docs目录）。有一个简单的解决方案吗？我可以简单地将GitHub README.md指向我的docs目录吗？有什么更优雅的吗？我一直在谷歌上罢工。

4

4 回答 4

36

我认为用 MarkDown 制作可用的 Javadoc 是不可能的。最好的解决方案可能是提交您在gh-pages分支上生成的 Javadoc（或在docs/目录中，具体取决于项目的设置）。它将在以下位置提供：

http://username.github.io/projectname

这是我的一个项目中的一个示例：

http://ebourg.github.io/jsign/apidocs/

于 2013-03-12T15:03:41.607 回答
24

目前，您还可以使用Github Pages不仅从分支托管Javadoc ，还可以直接从分支内的文件夹托管 Javadoc 。您可以在此处查看有关此主题的帮助部分（另请查看下面的附图）。gh-pages/docsmaster

在此处输入图像描述

另外，在 Github 上有一个项目，目标是将Javadoc 转换为 Markdown（还没有尝试过，只是留下参考）。

于 2016-10-19T10:23:54.297 回答
10

不要将 Javadocs 签入项目的源代码控制中

尤其不进master分行！在决定这是一个非常糟糕的主意之前，我关注了这个问题的其他答案大约一年。为什么？

  1. 这使得审查差异变得太困难了。我什至编写了一个脚本（见下文）来仅更新发生重大变化的 Javadoc 页面，但它仍然是一团糟。

  2. 它欺骗了 IntelliJ 的重构工具。我只是试图将 .x() 更改为 .getX() 并且不得不批准/拒绝 Javadocs 中的每个“x”。也许我忘了排除 IntelliJ 中的文件夹，但如果您曾经在项目中使用 sed/grep/find，则必须记住每次都将其排除。

  3. 它在 git 中添加了一堆不应该存在的数据，可能会使命令pull和clone命令花费更长的时间……永远！即使您稍后“删除”该文件夹，它仍然存储在 git 中。

javadocs应该去哪里？

最好将它们发布在https://javadoc.io/、您的网站或 AWS 或 heroku 上。如果您必须将 javadoc 签入源代码控制，请为 Javadocs 创建一个单独的项目，这样您就永远不需要查看差异。您可以按照其他人的答案来了解如何执行此操作。

“我看了你的帖子，但我还是这样做了”

这是我的脚本来更新更少的 javadocs。它仅将具有实质性更改的文件从target/apidocs文件夹复制到docs/apidocs文件夹。它还添加新文件并删除不再使用的文件。我想我用了不好的名字，newfileand oldfile，但它有效。我的意思是，仅仅证明将 javadoc 检查到我项目的源代码控制中是不够的，但它有帮助。

#!/usr/bin/env bash

# -I means ignore lines matching a regular expression
# -q means "quiet" - only tell whether files differ or not
# -r means "recursive" - explore subdirectories
# -N means "treat absent files as empty" which makes absent files show up in Quiet mode.
diff -I '<!-- Generated by javadoc ' \
     -I '<meta name="date" content="' \
     -I '<title>' \
     -I 'parent.document.title=' \
     -N \
     -qr \
     docs/apidocs/ target/apidocs/ > target/javadocPatch.txt

# Now read in the output file created by the previous command and
# Update only files that have substantial changes.
while read  ignore1 oldfile ignore2 newfile ignore3
do
  if [ ! -f "$oldfile" ]
  then
    echo "Added $oldfile"
    echo -n >$oldfile
    cp -fu $newfile $oldfile
  elif [ ! -f "$newfile" ]
  then
    echo "Deleted $newfile"
    rm $newfile
  else
    echo "cp -fu $newfile $oldfile"
    cp -fu $newfile $oldfile
  fi
done < "target/javadocPatch.txt"
于 2019-02-13T14:46:46.577 回答
8

这可能有点离题，但我相信 OP 正在寻找的是一种机制，可以在发布项目的新版本时自动使 javadoc 可用。

如果是这种情况，那么您可以尝试：http: //javadoc.io

它是一个免费的托管开源项目 javadocs 的服务，目前支持 maven central 和 bintray (jcenter)。

您可以生成指向项目最新版本的链接。例如，这个链接https://javadoc.io/doc/org.springframework/spring-core总是指向spring-core的最新版本，在我写这个答案的时候是5.2.0.RELEASE。

声明者：我运行 javadoc.io

于 2019-10-19T17:01:13.937 回答