Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://docs.pmd-code.org/latest/pmd_devdocs_writing_documentation.html below:

Writing documentation | PMD Source Code Analyzer

PMD’s documentation uses Jekyll with the I’d rather be writing Jekyll Theme.

Here are some quick tips.

The pages are in general in Github Flavored Markdown.

The documentation sources can be found in two places based on how they are generated:

• the ones that are manually written (like the one you are reading);
• and the ones that are generated automatically from the category files. All the rule documentation pages are generated that way.

All handwritten documentation is stored in the subfolders under docs/pages. The folder structure resembles the sidebar structure. Since all pages use a simple permalink, in the rendered html pages, all pages are flattened in one directory. This makes it easy to view the documentation also offline.

The categories for a language %lang% are located in pmd-%lang%/src/main/resources/category/%lang% . So for Java the categories can be found under pmd-java/src/main/resources/category/java. The XML category files in this directory are transformed during build into markdown pages describing the rules they contain. These pages are placed under docs/ like the handwritten documentation, and are then rendered with Jekyll like the rest of them. The rule documentation generator is the separate submodule pmd-doc.

Modifying the documentation of a rule should thus not be done on the markdown page, but directly on the XML rule tag corresponding to the rule, in the relevant category file.

The XML documentation of rules can contain GitHub flavoured markdown. Just wrap the markdown inside CDATA section in the xml. CDATA sections preserve all formatting inside the delimiters, and allow to write code samples without escaping special xml characters. For example:

<rule ...>
 <description>
 <![CDATA[
   Full description, can contain markup

   And paragraphs
 ]]>
 </description>
 ...
</rule>

We have some additional custom liquid tags that help in writing the documentation.

Here’s a short overview:

For the javadoc tags, the standard PMD maven modules are already defined as namespaces, e.g. core, java, apex, ….

For the implementation of these tags, see the _plugins folder.

There are two ways, to execute jekyll:

1. Using bundler. This will install all the needed ruby packages locally and execute jekyll:

   # this is required only once, to download and install the dependencies
   bundle install
   # this builds the documentation under _site
   bundle exec jekyll build
   # this runs a local webserver as http://localhost:4005
   bundle exec jekyll serve
   

2. Using docker. This will create a local docker image, into which all needed ruby packages and jekyll is installed.

   # this is required only once to create a local docker image named "pmd-doc"
   docker build --no-cache -t pmd-doc .
   # this builds the documentation under _site
   docker run --rm=true -v "$PWD:/src" pmd-doc build -H 0.0.0.0
   # this runs a local webserver as http://localhost:4005
   docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
   

The built site is stored locally in the (git ignored) directory _site. You can point your browser to _site/index.html to see the pmd documentation.

Alternatively, you can start the local webserver, that will serve the documentation. Just go to http://localhost:4005. If a page is modified, the documentation will automatically be rendered again and all you need to do, is refreshing the page in your browser.

See also the script pmd-jekyll.sh. It starts the jekyll server in the background and doesn’t block the current shell.

The sidebar is stored as a YAML document under _data/sidebars/pmd_sidebar.yml.

Make sure to add an entry there, whenever you create a new page.

Each page in jekyll begins with a YAML section at the beginning. This section is separated by 3 dashes (---). Example:

---
title: Writing Documentation
last_updated: January 2025 (7.10.0)
permalink: pmd_devdocs_writing_documentation.html
---

Some Text

# Some header

There are a couple of possible fields. Most important and always required are title and permalink.

By default, a page toc (table of contents) is automatically generated. You can prevent this with “toc: false”.

You can add keywords, that will be used for the on-site search: “keywords: documentation, jekyll, markdown”

It’s useful to maintain a last_update field. This will be added at the bottom of the page.

A summary can also be provided. It will be added in a box before the content.

For a more exhaustive list, see Pages - Frontmatter.

See Alerts.

For example, a info-box can be created like this:

{% include note.html content="This is a note." %}

It renders as:

Note: This is a note.

Other available types are:

• note.html
• tip.html
• warning.html
• important.html

A callout is created like this:

{% include callout.html content="This is a callout of type default.<br/><br/>There are the following types available: danger, default, primary, success, info, and warning." type="default" %}

It renders as:

This is a callout of type default.

There are the following types available: danger, default, primary, success, info, and warning.

This is as easy as:

``` java
public class Foo {
    public void bar() { System.out.println("x"); }
}
```

This looks as follows:

public class Foo {
    public void bar() { System.out.println("x"); }
}

mvn verify -pl pmd-doc. This only checks links within the site. HTTP links can be checked by specifying -Dpmd.doc.checkExternalLinks=true on the command line.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4