在GitHub上显示JavaDocs

Question

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

Answer 1

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

http://username.github.io/projectname

以下是我的一个项目的示例：

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

Answer 2

目前，您还可以使用 Github页来托管 Javadoc ，而不仅仅是gh-pages分支，而是直接来自您的/docs文件夹master分支。您可以查看有关此主题的帮助部分here（另请参阅下面附带的图片）。

此外，Github上的一个项目针对Javadoc to Markdown的一些转换（尚未尝试过，只是留下参考）。

Answer 3

这可能是个话题，但我相信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

Answer 4

请勿将Javadocs签入项目的源代码管理中

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

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

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

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

javadocs应该去哪里？

最好将它们发布在您的网站，AWS或heroku上。如果必须将javadoc检入源代码管理，请为Javadocs创建一个单独的项目，这样就无需查看diff。您可以按照其他人的回答进行操作。

“我读了你的帖子，但我还是在做”

这是我的脚本，用于更新较少的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"