#1049 Migrate developer documentation to main repository

[GuusLieben]

Type of Change

• Documentation (documentation changes)
• Chore (changes to the build process or auxiliary tools)

Description

Summary

Currently our documentation is developed and maintained at https://github.com/Dockbox-OSS/HartshornDocs. While this is a convenient setup, it makes it hard to keep documentation up to date for new releases. As such, these changes migrate our documentation away from mkdocs, and now allow us to place documentation directly in our various modules, and publish using Antora.

Writing and building

Documentation can be written using the Asciidoc format, and can be published either locally (unversioned) or for release (versioned) using pre-made playbooks in our assembly directory.

Custom UI bundle

To customize the look and feel of our documentation, we have a custom UI bundle which is developed at https://github.com/Dockbox-OSS/Antora-Dockbox-UI. A sample of this UI bundle can be seen below.

CI integration

To automatically check for documentation issues, and optionally get a quick preview of the documentation for a specific pull request, a CI workflow has been added to build and publish the documentation. An overview of executions of this workflow can be found at https://github.com/Dockbox-OSS/Hartshorn/actions/workflows/build.docs.yml. Note that artifacts are only retained for 7 days.

Checklist

• I have performed a self-review of my own code
• Related issue number is linked in pull request title
• I have added documentation that describes my changes
• Any dependent changes have been merged and published in downstream modules
• I have rebased my branch on top of the latest develop branch

Related Issue

Closes #1049

[GuusLieben]

Pending work:

• Correct icon for 'View on GitHub' on production
• Correct paths for 'edit this page'
• Integrate Antora execution into CI