3

I want to include an element in the <head> of my generated Javadoc HTML:

<link rel="shortcut icon" href="my-project-icon.ico" />

Note that I'm using an Ant task to generate the Javadoc.

I tried using the <header> element of the Ant task, but any markup placed there ends up within an <h1> tag, which is invalid and therefore ignored by the browser.

Drew Noakes
  • 300,895
  • 165
  • 679
  • 742

3 Answers3

2

I would definitely modify the output files as an easy brute force solution. But a sophisticated way would be to have a custom doclet. This doclet would be a copy of standard doclet (Where can you download the source for the standard JavaDoc doclet for current releases (1.5 or 1.6)).

In HtmlDocletWriter.java there are many lines head.addContent. You would add one more such a line, perhaps based on HtmlTree.LINK.

Community
  • 1
  • 1
Jarekczek
  • 7,456
  • 3
  • 46
  • 66
2

We take the "brute force" approach using the following bash/sed script.

(Please note, javadoc creates some ugly files called "*.html" in the created directories, which lead to an error message when sed tries to process them. We haven't figured out yet how to avoid this, but it seems to be harmless for our purpose !-)

Of course, an xslt script would be more professional, ...

#!/bin/sh
# patch favicon into header of javadoc generated api doc html 
#
# assume started with P=`pwd` , then the args must be
# 1 directory to process / full path relative to  $P
# 2 favicon filename to insert / full path relative to $P
function patchIt () {
   for f in $1/*.html ; do  
     tmpfile=`mktemp -p . `
     sed -e " s%<HEAD>%<HEAD><link rel=\"icon\" href=\"$2\" type=\"image/png\"/>%" \
         $f > $tmpfile  ; mv $tmpfile  $f ; 
   done ; 
   for d in $1/* ; do 
     if [ -d $d ]; then echo "descending to "$d ; patchIt $d ../$2 ; fi ; 
   done
}
patchIt $1 $2 
#eof
markus
  • 21
  • 1
2

Markus's solution is a good start. Thanks for providing it!

However, it has some problems:

  • If a directory does not contain any .html files, it creates a file named *.html.
  • It does not add a favicon to HTML files generated by the JDK 8 version of javadoc, which uses <head> instead of <HEAD>.
  • If run multiple times, it inserts the favicon multiple times.
  • The mktemp command is not portable (it doesn't work on Mac OS, for example).
  • It does not preserve file permissions.

Here is a version that corrects these issues. An expanded version can be found in the html-tools repository. If you find problems or want to propose improvements, please comment here or use the html-tools issue tracker.

#!/bin/sh
# Add favicon to header of HTML files.
# One use case is for javadoc-generated API documentation.
#
# Run like this:
# add-favicon <directory> <favicon.png>
# The arguments should be paths relative to the current working directory.

# Once this has been run, running it another time has no effect.

patchIt () {
  for f in $1/*.html ; do
    if [ -f "$f" ]; then     # if no .html files exist, f is literal "*.html"
      tmpfile=`mktemp patch_favicon_XXXXX`
      # This creates tmpfile, with the same permissions as $f.
      # The next command will overwrite it but preserve the permissions.
      # Hat tip to http://superuser.com/questions/170226/standard-way-to-duplicate-a-files-permissions for this trick.
      \cp -p $f $tmpfile
      sed -e " s%<head>\$%<head><link rel=\"icon\" href=\"$2\" type=\"image/png\"/>%" $f > $tmpfile
      mv -f $tmpfile $f
    fi;
  done ;
  for d in $1/* ; do
    if [ -d $d ]; then echo "descending to "$d ; patchIt $d ../$2 ; fi ;
  done
}

patchIt $1 $2

#eof
mernst
  • 7,437
  • 30
  • 45