Contributing to the Documentation¶

Note

This document provides information on contributing to the Adventure documentation. For more information on contributing to Adventure or any of the other Kyori projects themselves, consult each project’s README.

Thank you for your interest in contributing to the Adventure documentation. We use Sphinx to build the documentation, along with several extensions. This page aims to be a quick rundown of what is needed to build the documentation, and some useful syntax.

Building¶

Sphinx is a Python tool, so the steps to build this documentation will be familiar to anyone who’s set up a Python project before.

Note

For those wishing to make a simple contribution quickly, we provide a GitHub Codespaces configuration file for this repository allowing for quick setup with VS Code as an editor.

Make sure Git and Python 3.7 or newer are installed. These instructions assume you are working from a terminal, either on Windows or Linux.

Linux/macOS (POSIX)

Clone the repository from GitHub and switch into the directory
Install pipenv (if not present): $ apt install pipenv
Install the dependencies: pipenv install
Build the documentation: pipenv run make livehtml
Open a browser to https://localhost:8000 to view the just-built site. Pages will auto-refresh when changes are made.

Windows (PowerShell)

Clone the repository from GitHub and switch into the directory
Install pipenv (if not present): pip install pipenv`
Install the dependencies: pipenv install
Build the documentation: pipenv run ./make livehtml
Open a browser to https://localhost:8000 to view the just-built site. Pages will auto-refresh when changes are made.

Any text editor will work for editing the documentation, but we’ve had the best experience with Visual Studio Code or vim, each of which have mature reST plugins. A typical development environment has a text editor and web browser side-by-side, with the web browser viewing the locally served test site.

Once you’ve written changes, they can be submitted for inclusion in the docs with a GitHub Pull Request.

Style¶

The Adventure documentation is written in English. We attempt to mostly follow American spellings, though that can often be inconsistent. There is a basic spellchecker that will be run on PRs, or which can be run locally with the pipenv run make spelling command. We also recommend using the LanguageTool VS Code extension for in-editor suggestions. For technical language that should always be accepted, custom words can be added in the .config/spelling_wordlist.txt file. For one-off exceptions (such as project names), use the :spelling:ignore:`word`

All code samples should be given in Java.

When providing examples for build tools, those examples should be provided for Maven, Gradle with Groovy buildscript, and Gradle with Kotlin buildscript.

Helpful Roles and Directives¶

Source for this documentation is primarily in the reStructured Text format, the default used by Sphinx. The syntax may be a touch different from what many people are used to, but the documentation for reST should give a good overview. There are still many included directives and roles, especially once Sphinx’s extensions enter the mix, so here are some of the less common ones.

New pages can alternatively be written in Markdown. We use the MyST Parser package to support Markdown with several Sphinx-specific extensions to support roles and directives. See their documentation for more information.

Standard Sphinx/Docutils¶

See the Sphinx documentation on Roles and Directives for a full listing.

Plugins we use¶

We take advantage of some of the many Sphinx plugins available to add helpful tools to the documentation site.

sphinx-design: Many useful directives for page layout assistance, and tab views for displaying alternative versions of syntax side by side.
Sphinx-Substitution-Extensions: Allows substitution within code blocks, used for build setup instructions.
sphinx-github-changelog: This plugin will likely not be interesting to most contributors, but it powers the changelogs included for Adventure projects.
sphinx-reredirects: If it makes sense to change the URL of a documentation page, this plugin allows inserting redirects from the old page to the new one.

Custom for this documentation¶

While we try to rely on external projects as much as possible, there are some small features that are specific to the Adventure documentation.

:java:¶

The :java: (or {java} in Markdown) role will insert its contents as an inline syntax-highlighted code block.

For example, :java:`Component.text("Hello world", NamedTextColor.RED)` will produce Component.text("Hello world", NamedTextColor.RED)

:mojira:¶

The :mojira: role can insert references to Mojang’s issue tracker for Minecraft issues.

For example, :mojira:`MC-4` (or {mojira}`MC-4` in Markdown) will produce MC-4

.. kyori-dep::¶

The kyori-dep directive inserts a dependency block for a Kyori module. The directive takes two parameters, artifact and version type (api, platform, platform_fabric, or ansi).

For example, ..kyori-dep:: adventure-api api will produce:

Declaring the dependency:

Maven

 <dependency>
    <groupId>net.kyori</groupId>
    <artifactId>adventure-api</artifactId>
    <version>4.17.0</version>
 </dependency>

Gradle (Groovy)

 repositories {
    mavenCentral()
 }

 dependencies {
    implementation "net.kyori:adventure-api:4.17.0"
 }

Gradle (Kotlin)

 repositories {
    mavenCentral()
 }

 dependencies {
    implementation("net.kyori:adventure-api:4.17.0")
 }

Need development/snapshot builds? Using Snapshot Builds

MiniMessage syntax¶

This documentation has MiniMessage syntax highlighting enabled. In code blocks, this can be used with the mm or minimessage languages:

This is <bold>a MiniMessage <hover:show_text:'<rainbow>hi'>string</hover>!

Inline, the :mm: (or {mm} in Markdown) role can be used.

:mm:¶

The :mm: role will insert an inline code block containing MiniMessage-highlighted text.

For example, :mm:`hello <ul>world` will produce hello <ul> world