Display JavaDocs on GitHub

Question

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 simple solution to display my documentation on GitHub (shy of simply adding a docs directory). Is there a simple solution for this? Can I simply point the GitHub README.md to my docs directory? Is there something more elegant? I have been striking out on Google.

Answer 1

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 GitHub 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/

I used to do this but nowadays I just rely on javadoc.io to host the Javadoc:

https://javadoc.io/doc/net.jsign/jsign/

The documentation is picked automatically from Maven Central, this saves the extra step of commiting the files into the Git repository when preparing a new release.

Answer 2

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).

Answer 3

Do NOT check Javadocs into the source control for your project

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?

1. 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.

2. 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.

3. 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.

Where should javadocs go?

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.

"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/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"

Answer 4

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