我正在寻找一种将 javadocs 从我的开源项目（在 Eclipse 中生成）转换为 GitHub MarkDown 的方法，或者想出一些其他简单的解决方案来在 GitHub 上显示我的文档（只是简单地添加一个 docs 目录）。有一个简单的解决方案吗？我可以简单地将 GitHub README.md 指向我的 docs 目录吗？有什么更优雅的吗？我一直在 Google 上大放异彩。
【问题讨论】：
标签： java github javadoc markdown
我认为使用 MarkDown 制作可用的 Javadoc 是不可能的。最好的解决方案可能是提交您在gh-pages 分支上生成的Javadoc（或在docs/ 目录中，具体取决于您的项目设置）。它将在以下位置提供：
http://username.github.io/projectname
这是我的一个项目的示例：
【讨论】：
docs/ 目录下的代码相同的分支上。这可以从项目设置中启用。
目前，您还可以使用 Github Pages 托管您的 Javadoc，不仅可以来自 gh-pages 分支，还可以直接来自 master 分支中的 /docs 文件夹.您可以查看有关此主题的帮助部分，here（也可以查看下面的附图）。
另外，Github 上有一个项目针对Javadoc to Markdown 的一些转换（还没有尝试过，只是留下参考）。
【讨论】：
尤其不要进入master 分支！在决定这是一个非常糟糕的主意之前，我关注了这个问题的其他答案大约一年。为什么？
这让查看差异变得非常困难。我什至编写了一个脚本（见下文）来仅更新发生重大变化的 Javadoc 页面，但它仍然是一团糟。
它欺骗了 IntelliJ 的重构工具。我只是试图将 .x() 更改为 .getX() 并且不得不批准/拒绝 Javadocs 中的每个“x”。也许我忘记在 IntelliJ 中排除该文件夹，但如果您曾经在项目中使用 sed/grep/find，则必须记住每次都排除它。
它在 git 中添加了一堆不应该存在的数据，可能会使 pull 和 clone 命令花费更长的时间......永远！即使您稍后“删除”该文件夹，它仍然存储在 git 中。
最好将它们发布在https://javadoc.io/、您的网站、AWS 或 heroku 上。如果您必须将 javadoc 签入源代码控制，请为 Javadocs 创建一个单独的项目，这样您就永远不需要查看差异。您可以按照其他人的回答来了解如何执行此操作。
这是我的脚本来更新更少的 javadocs。它仅将具有重大更改的文件从target/apidocs 文件夹复制到docs/apidocs 文件夹。它还添加新文件并删除不再使用的文件。我想我用了不好的名字，newfile 和 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"
【讨论】：
这可能有点离题，但我相信 OP 正在寻找的是一种机制，可以在发布项目的新版本时自动使 javadoc 可用。
如果是这种情况，那你可以试试：http://javadoc.io
它是一个免费的托管开源项目 javadocs 的服务，目前支持 maven central 和 bintray (jcenter)。
您可以生成指向项目最新版本的链接。例如这个链接https://javadoc.io/doc/org.springframework/spring-core总是指向最新版本的spring-core，在我写这个答案的时候是5.2.0.RELEASE。 p>
声明：我运行 javadoc.io
【讨论】：