在GitHub上显示JavaDocs

Question

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

Answer 1

我认为用MarkDown制作一个可用的Javadoc是不可能的.最好的解决方案可能是提交您在gh-pages分支上(或docs/根据项目设置在目录中)生成的Javadoc .它将在以下时间提供:

http://username.github.io/projectname

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

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

Answer 2

目前,您还可以使用Github Pages来托管您的Javadoc,不仅可以从分支机构托管,也可以直接从分支机构的文件夹托管.您可以在此处查看有关此主题的帮助部分(另请参阅下面的附图).gh-pages/docsmaster

另外,在Github上有一个项目,目标是将Javadoc转换为Markdown(还没有尝试过,只留下参考).

Answer 3

不要将 Javadoc 签入项目的源代码管理中

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

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

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

3. 它增加了一堆Git的数据，只是不应该存在的，潜在地使pull和clone命令需要更长的时间...永远！即使您稍后“删除”该文件夹，它仍然存储在 git 中。

javadoc 应该去哪里？

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

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

这是我更新较少 javadoc 的脚本。它仅将具有实质性更改的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"

Answer 4

这可能有点离题，但我相信 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