I\'m looking for a way to convert the javadocs from my open source project (generated in Eclipse) to GitHub MarkDown, or come up with some other s
Especially not into the master
branch! I followed the other answers to this question for about a year before deciding it was a really bad idea. Why?
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 pull
and clone
commands take longer... FOREVER! Even if you later "remove" the folder, it's still stored in git.
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.
Here's my script to update fewer javadocs. It only copies files with substantial changes from the target/apidocs
folder to the docs/apidocs
folder. It also adds new files and deletes no longer used ones. I think I used poor names, newfile
and oldfile
, but it works. I mean, it wasn't enough to justify checking javadoc into my project's source control, but it helps.
#!/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"
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-pages
branch (or in the docs/
directory depending on the settings of your project). It will be available at :
http://username.github.io/projectname
Here is an example from one of my projects:
http://ebourg.github.io/jsign/apidocs/
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.
If this is the case, then you can try: http://javadoc.io
It's a free service hosting javadocs for open source project, currently supporting maven central and 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-core always point to the latest version of spring-core, which is 5.2.0.RELEASE at the time I write this answer.
Declaimer: I run javadoc.io
Currently you can also host your Javadoc with Github Pages from not only a gh-pages
branch, but directly from the /docs
folder within your master
branch. You can check the help section on this topic, here (also check attached image below).
Also, there's a project on Github that targets some conversion of Javadoc to Markdown (have not tried it yet, just leaving the reference).