# Documentation Generation ## About The **Documentation Generation** category in Maven encompasses plugins that generate project documentation in standardized formats such as **Javadoc**, **project reports**, or **custom site documentation**. These tools play a critical role in delivering readable, maintainable, and shareable technical information—especially for large codebases, open-source projects, or enterprise systems. They help automate the creation of: * API documentation (e.g., Javadoc) * Project metadata (build info, dependencies, plugins) * Custom written pages * Multi-module documentation sites ## Maven Javadoc Plugin The **Maven Javadoc Plugin** generates Javadoc API documentation for our Java source code. This is one of the most commonly used documentation plugins and is often configured for both site generation and direct Javadoc generation. #### **Common Goals** | Goal | Description | | ---------------------- | ----------------------------------------------------- | | `javadoc:javadoc` | Generates Javadoc for the current module | | `javadoc:aggregate` | Generates combined Javadoc for a multi-module project | | `javadoc:test-javadoc` | Generates Javadoc for test classes | #### **Basic Configuration** ```xml org.apache.maven.plugins maven-javadoc-plugin 3.6.3 UTF-8 none false ``` #### **Additional Configurations** | Element | Purpose | | ----------------------- | ------------------------------------------------ | | `doclint` | Turn off strict lint checks (useful for Java 8+) | | `excludePackageNames` | Exclude certain packages from documentation | | `reportOutputDirectory` | Customize output folder | | `source` | Set Java version for Javadoc parsing | ## **Maven Site Plugin** The **Maven Site Plugin** generates a full website for our project including reports, documentation pages, and Javadoc. It can also deploy the generated site to a remote server or repository. It pulls in content from various report-generating plugins like Checkstyle, PMD, Surefire, and more. #### **Common Goals**
GoalDescription
site:siteGenerates the site in the target/site folder
site:deployDeploys the site to a remote server (e.g., GitHub Pages)
site:stagePrepares a staged version of the site
#### **Basic Configuration** ```xml org.apache.maven.plugins maven-site-plugin 4.0.0-M14 ``` #### **Site Descriptor (`src/site/site.xml`)** This file allows us to customize menus, pages, reports, and the structure of the site. Example: ```xml ``` #### **Supported Documentation Formats** * **APT (Almost Plain Text)** * **XHTML** * **Markdown** * **FML (FAQ Markup Language)** Place content under: `src/site/markdown`, `src/site/apt`, etc. {% hint style="info" %} **Doxia Tools** The **Doxia module** is the underlying framework used by the Maven Site Plugin for rendering various markup formats (Markdown, APT, etc.). Although not typically configured directly as a plugin, understanding Doxia is useful if we want to extend or customize our documentation formats. We typically work with Doxia when * Writing custom site generators * Working on Maven extensions * Integrating documentation with custom lifecycle phases {% endhint %} ### **Asciidoctor Maven Plugin** For projects requiring **rich, styled, and versioned documentation**, the **Asciidoctor Maven Plugin** allows writing technical documentation using [Asciidoctor](https://asciidoctor.org/), which is popular for developer-focused projects and docs-as-code workflows. #### **Common Goals:** | Goal | Description | | ------------------------------ | ------------------------------------- | | `asciidoctor:process-asciidoc` | Converts `.adoc` files to HTML or PDF | | `asciidoctor:output-html` | Output to HTML | | `asciidoctor:output-pdf` | Output to PDF | #### **Basic Configuration** ```xml org.asciidoctor asciidoctor-maven-plugin 2.2.1 process-asciidoc ``` Place documentation in `src/docs/asciidoc`. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://www.pranaypourkar.co.in/the-programmers-guide/maven/plugins/documentation-generation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.