java 在 GitHub 上显示 JavaDocs
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/15347808/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Display JavaDocs on GitHub
提问by Phil
I'm looking for a way to convert the javadocsfrom my open source project (generated in Eclipse) to GitHub MarkDown, or come up with some other simple solution to display my documentation on GitHub(shy of simply adding a docsdirectory). Is there a simple solution for this? Can I simply point the GitHubREADME.mdto my docsdirectory? Is there something more elegant? I have been striking out on Google.
我正在寻找一种方法将javadocs从我的开源项目（在Eclipse 中生成）转换为GitHub MarkDown，或者想出一些其他简单的解决方案来在GitHub 上显示我的文档（避免简单地添加一个docs目录）。有没有一个简单的解决方案？我可以简单地将GitHubREADME.md指向我的docs目录吗？有没有更优雅的东西？我一直在Google 上脱颖而出。
采纳答案by Emmanuel Bourg
I don't think it's possible to make a usable Javadoc with MarkDown. The best solution is probably to commit the Javadoc you generated on the gh-pagesbranch (or in the docs/directory depending on the settings of your project). It will be available at :
我认为用 MarkDown 制作可用的 Javadoc 是不可能的。最好的解决方案可能是提交您在gh-pages分支（或docs/目录中，具体取决于您的项目设置）上生成的 Javadoc 。它将在以下位置提供：
http://username.github.io/projectname
http://username.github.io/projectname
Here is an example from one of my projects:
这是我的一个项目中的一个示例：
回答by acoelhosantos
Currently you can also host your Javadocwith Github Pagesfrom not only a gh-pagesbranch, but directly from the /docsfolder within your masterbranch. You can check the help section on this topic, here(also check attached image below).
目前，您还可以使用Github Pages托管您的Javadoc，不仅可以从分支，还可以直接从分支内的文件夹。您可以在此处查看有关此主题的帮助部分（另请查看下面的附加图片）。gh-pages/docsmaster
Also, there's a project on Github that targets some conversion of Javadoc to Markdown(have not tried it yet, just leaving the reference).
另外，Github 上有一个项目，目标是将Javadoc转换为 Markdown（还没有尝试过，只是留下参考）。
回答by GlenPeterson
Do NOT check Javadocs into the source control for your project
不要将 Javadoc 签入项目的源代码管理中
Especially not into the masterbranch! I followed the other answers to this question for about a year before deciding it was a really bad idea. Why?
尤其不进master分行！在决定这是一个非常糟糕的主意之前，我遵循了这个问题的其他答案大约一年。为什么？
It made it too difficult to review diffs. I even made a script (see below) to update only the Javadoc pages that substantially changed, but it still was a mess.
It fooled IntelliJ's refactoring tools. I just tried to change .x() to .getX() and had to approve/reject every "x" in the Javadocs. Maybe I forgot to exclude the folder in IntelliJ, but if you ever use sed/grep/find on your project, you have to remember to exclude it every time.
It adds a bunch of data in git that just shouldn't be there, potentially making
pullandclonecommands take longer... FOREVER! Even if you later "remove" the folder, it's still stored in git.
这使得差异变得太困难。我什至制作了一个脚本（见下文）来仅更新发生重大变化的 Javadoc 页面，但它仍然是一团糟。
它愚弄了 IntelliJ 的重构工具。我只是尝试将 .x() 更改为 .getX() 并且不得不批准/拒绝 Javadoc 中的每个“x”。也许我忘了排除 IntelliJ 中的文件夹，但是如果您曾经在项目中使用 sed/grep/find，则必须记住每次都排除它。
它增加了一堆Git的数据，只是不应该存在的，潜在地使
pull和clone命令需要更长的时间...永远！即使您稍后“删除”了该文件夹，它仍然存储在 git 中。
Where should javadocs go?
javadoc 应该去哪里？
It's probably best to post them on https://javadoc.io/, your web site, or AWS or heroku. If you must check javadoc into source control, make a separate project just for Javadocs so you'll never need to look at the diff. You can follow other people's answers for how to do this.
最好将它们发布在https://javadoc.io/、您的网站、AWS 或 heroku 上。如果您必须将 javadoc 签入源代码管理，请为 Javadoc 创建一个单独的项目，这样您就无需查看差异。您可以按照其他人的答案来了解如何执行此操作。
"I read your post, but I'm doing it anyway"
“我读了你的帖子，但我还是在做”
Here's my script to update fewer javadocs. It only copies files with substantial changes from the target/apidocsfolder to the docs/apidocsfolder. It also adds new files and deletes no longer used ones. I think I used poor names, newfileand oldfile, but it works. I mean, it wasn't enough to justify checking javadoc into my project's source control, but it helps.
这是我更新较少 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"
回答by Max
It might be a bit off topic but I believe what OP is looking for is a mechanism to automatically make javadoc available as a new version of the project is published.
这可能有点离题，但我相信 OP 正在寻找的是一种机制，可以在项目的新版本发布时自动使 javadoc 可用。
If this is the case, then you can try: http://javadoc.io
如果是这种情况，那么您可以尝试：http: //javadoc.io
It's a free service hosting javadocs for open source project, currently supporting maven central and bintray (jcenter).
它是一个免费服务，托管开源项目的 javadoc，目前支持 maven central 和 bintray (jcenter)。
You can generate a link to the latest version of your project. For example, this link https://javadoc.io/doc/org.springframework/spring-corealways point to the latest version of spring-core, which is 5.2.0.RELEASEat the time I write this answer.
您可以生成指向项目最新版本的链接。例如，这个链接https://javadoc.io/doc/org.springframework/spring-core总是指向spring-core的最新版本，在我写这个答案时是5.2.0.RELEASE。
Declaimer: I run javadoc.io
声明：我运行 javadoc.io
