Skip to content

Migrate the AssertJ documentation to Antora and publish it at docs.assertj.dev #2

Open
0 of 6 issues completed
Open

Description

@marcphilipp

Each AssertJ module has the source code in a separate repository, but all the documentation is maintained in a common repository. When a relevant change is contributed to a module, a separate PR must be made to the documentation repository. Ideally, the documentation for each module should close to its code, so contributions can be made in a single PR. Moreover, the current documentation lacks a version picker. Users may see features that don't yet exist in the version they're using.

Another issue is that the documentation links to javadoc.io, a third-party platform for hosting the AssertJ Javadoc. Over the past few years, javadoc.io has experienced several outages. This harms users trying to access the API documentation, as well as downstream projects (e.g., JUnit) that links their Javadoc against AssertJ’s Javadoc, as their builds fail when javadoc.io is unavailable.

To resolve this, we want to adopt Antora to build documentation, supporting per-module versioning and sourcing documentation from multiple repositories. This requires roughly the following steps:

  1. Migrate module-specific documentation into the corresponding repositories and convert/split the content from plain Asciidoctor to Antora pages
  2. Set up an Antora site sourcing from the module-specific repositories
  3. Publishing Javadoc alongside the documentation site so it becomes self-hosted
  4. Setting up CI workflows for building the Antora site
  5. Integrating those workflows into the module’ release processes

Lastly, the new site should be published under a new docs.assertj.dev domain.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions