Writing Documentation
| You will need to familiarise yourself with both to be contribute to documentation. Start with the Antora docs. |
Repo structure
Each documented repo has a /docs folder that conforms to Antora’s specifications. At the very least:
.
├── docs
│ ├── antora.yml
│ └── modules
│ └── ROOT
│ └── pages
│ └── overview.adocIncluding Your Repo
To include your repo, you must add a reference to it in the /antora-playbook.yml file in the smc-docs repository.
content:
sources:
- url: https://example.com/repo.gitVersioning and Branches
If the repo has is versioned, you might want to consider calling these out explicitly.
I like to move away from having a main or master branch as it’s never really clear to other developers what the semantics of these are.
This confusion is avoided by explicitly stating the intention in the branch name for every branch.
e.g. I favour a dev branch for continuing development (which is basically what most people use main for, but explicitly named!), with branches for desired versions. Al
|
If you need to create a special branch and wish it to appear in the docs, its antora version must not be the same as any other branch referenced in the playbook for this repo. Otherwise, you can give this branch a unique version - like, for example, the branch name.
In the repo
The version number is stored in the docs/antora.yml file in the repo, along with an optional line declaring the version as prerelease or not.
If you are using a dev branch for daily development, your dev branch should have an antora.yml with the following lines:
version: dev
prerelease: trueIf you then create a version that you wish to document, create a branch - say v2.0.1 - and update your antora.yml with the following lines:
version: 2.0.1
prerelease: false
You can also just remove the prerelease line.
|
Merging Branches
As the version is stored in a file in the branch, it can get blatted by merges. If your versioning approach regularly merges across versioned branches, to ensure the versions are retained you will need to enable a special git merging driver:
$ git config --global merge.ours.driver trueThen, in the /docs directory in your repo add a .gitattributes file with the following content:
antora.yml merge=oursNow, when you merge, this file should not overwrite across branches.
It would be wise to ensure this .gitattributes file is present in both branches before you start doing your merges.
… And maybe test it. It’s mostly worked, but I did have some strange behaviours at some points. Al
|
In the Playbook
In the central playbook, you need to explicitly call out all the branches that you want included. The versions will be automatically picked up by Antora. There probably isn’t a need to store every version. It depends on the release versioning strategy for the repo in question.
| At the very least you should include what’s currently in production - whether that’s a semver or named branch (or both). Adding the dev docs can be helpful if working collaboratively with another developer on a feature. |
e.g.
- url: https://example.com/repo.git
branches: [dev, 1.2.3, 2.0.1]