Cambiar y personalizar los estilos de la documentación Javadoc

Escrito por el .
blog-stack java planeta-codigo" programacion
Comentarios

Java

La documentación generada por la herramienta Javadoc se puede adaptar a las necesidades propias ya que tiene mecanismos para extenderla. Crear un taglet propio es una forma pero también se pueden modificar los estilos aplicados al HTML generado, por ejemplo, para adaptar el Javadoc a los colores de la organización o para incluir un logotipo en la cabecera o un texto en el pie de página.

El comando javadoc con el que se genera la documentación posee opciones para modificar la cabecera, el pie de página o usar una hoja de estilos propia. Estas opciones son -header, -footer y -stylesheetfile. Un punto de partida para modificar los estilos es usar la hoja de estilos generada por defecto, realizar en ella las modificaciones oportunas y finalmente indicar que se use con el opción -stylesheetfile.

En el caso de este ejemplo en vez de usar el color azul por defecto he modificado la hoja de estilos para que sea uno verde. En los cambios he partido de la hoja de estilos original del javadoc e inspeccionando los elementos con las herramientas del navegador para sustituir sus colores por otros de una paleta de colores basada en el verde en la que cambia la tonalidad de color hacia más claro. También se puede modificar la cabecera y el pie de página para incluir una nota con un mensaje de derechos de autor o un enlace y añadir nuevos estilos para el taglet todo.

1
2
3
4
5
6
7
8
9
.todoLabel {
    font-size: 12px;
    font-weight: bold;
}

ul.todo li {
    font-size: 14px;
    font-family: 'DejaVu Serif', Georgia, "Times New Roman", Times, serif;
}

La tarea de Gradle para generar la documentación Javadoc posee opciones equivalentes al comando javadoc, unas de ellas como ejemplo son footer y bottom que añaden un texto en en el pie de página de cada página.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
apply plugin: 'java'
apply plugin: 'application'

sourceCompatibility = 1.8
targetCompatibility = 1.8

mainClassName = 'io.github.picodotdev.blogbitix.javadoc.Main'

repositories {
    jcenter()
}

dependencies {
    compile files("/usr/lib/jvm/default/lib/tools.jar")
}

javadoc {
    options.charSet = 'UTF-8'
    options.encoding = 'UTF-8'
    options.tagletPath = [new File ('build/classes/java/main/')]
    options.taglets = ['io.github.picodotdev.blogbitix.javadoc.TodoTaglet']
    options.stylesheetFile = new File('src/main/resources/stylesheet.css')
    //options.footer = "Copyleft © 2017 Blog Bitix"
 //options.bottom = "Copyleft © 2017 Blog Bitix"
}

task javadocZip(type: Zip) {
    dependsOn javadoc
    classifier 'javadoc'
    from 'build/docs/javadoc/'
}

artifacts {
    archives javadocZip
}
Estilos personalizados de la documentación Javadoc
Estilos por defecto de la documentación Javadoc

El comando javadoc tiene una buena cantidad de opciones, con la opción -help se obtiene una listado y descripción de cada una de ellas. Dependiendo del destinatario de la documentación, se pueden limitar las clases que son incluidas en el Javadoc si por ejemplo solo se quiere ofrecer la documentación de la parte pública.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
$ javadoc -help
...
-public                         Show only public classes and members
-protected                      Show protected/public classes and members (default)
-package                        Show package/protected/public classes and members
-private                        Show all classes and members
...
-doctitle <html-code>         Include title for the overview page
-header <html-code>           Include header text for each page
-footer <html-code>           Include footer text for each page
-top    <html-code>             Include top text for each page
-bottom <html-code>           Include bottom text for each page
-linksource                     Generate source in HTML
-stylesheetfile <path>         File to change style of the generated documentation
...

El código fuente completo del ejemplo puedes descargarlo del repositorio de ejemplos de Blog Bitix alojado en GitHub y probarlo en tu equipo ejecutando el comando ./gradlew javadoc.