Danger

The Adventure docs are currently a work in progress and supplement the Javadocs. Some areas may have limited coverage or may not be entirely up to date. Feel free to join our Discord if you have any questions.

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.

Make sure Git and Python 3.7 or newer are installed. Virtualenv is also highly recommened to maintain an isolated environment for this project’s dependencies. These instructions assume you are working from a terminal, either on Windows or Linux.

  1. Clone the repository from GitHub and switch into the directory

  2. (optional) Set up a Virtualenv in the checkout director: virtualenv ENV, and activate it: . ENV/bin/activate

  3. Install the dependencies: pip install -r requirements.txt

  4. Build the documentation: make livehtml

  5. Open a browser to https://localhost:8000 to view the just-built site. Pages will auto-refresh when changes are made.

  1. Clone the repository from GitHub and switch into the directory

  2. (optional) Set up a Virtualenv in the checkout director: virtualenv ENV, and activate it: ENV/Scripts/Activate.ps1

  3. Install the dependencies: pip install -r requirements.txt

  4. Build the documentation: ./make livehtml

  5. 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 rST 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.

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 in the reStructured Text format, the default used by Sphinx. The syntax may be a touch different than what many people are used to, but the documentation for rST should give a good overview. There are still a large number of included directives and roles, especially once Sphinx’s extensions enter the mix, so here are some of the less common ones.

Standrd Sphinx/Docutils#

See the Sphinx documenattion 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: 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` will produce MC-4

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: 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