Documentation

The whole ArCo docs project and every modular piece of software built in ArCo is managed in a Docs as Code manner. That means that our documentation process benefits from the same practices used to produce software or infrastructure in an IaC project.

Some of these practices include:

  • Storing content in a version control system

  • Separating content, configuration, and presentation

  • Leveraging automation for compilation, validation, verification, and publishing

  • Reusing shared materials (DRY)

In order to help in this Docs as Code initiative, the ArCo docs project is built over the Antora site generator and written using the AsciiDoc syntax and processor.

Antora

The Antora tool handles all aspects of creating a documentation site, from fetching and aggregating to converting and arranging the content and publishing the files of the generated site. We’ll describe the main parts in the following sections.

UI Project

The Antora UI Project contains the UI assets (page templates, CSS, JavaScript, images, etc.) for the documentation site, and a Gulp build script. The build script can be used to preview the UI locally, or to package it for consumption by the Antora site generator playbook. We will refer to this package as the ArCo UI bundle.

Use the Antora Default UI project docs to help you in the development process if needed.

Playbook file

The Antora playbook file is simple a configuration file that can be written in YAML, JSON, or TOML. It contains information and settings such as what content to use, how the content should be processed, how the site should be generated, and where to publish the output.

Using the content sources listed in the playbook, Antora loads the specified git repositories in preparation to scan them for content files. For each remote URL, Antora clones the remote git repository and determines which references (branches and/or tags) to use from the specified repositories.

Components

A documentation component is a set of files that are versioned together and usually share a common subject, such as all the content source files for a software product.

Antora identifies a group of files as a documentation component when it finds a component descriptor file named antora.yml in the project.

Component source files can be stored in a single repository, at the root of a repository or in a sub-path, or distributed across multiple repositories.

Release process

UI Project

The UI project is built whenever a new change is made in the project master branch. There is a GitLab pipeline with 3 stages: setup, verify, and deploy.

  1. The setup stage will run npm install in order to get the Node.js dependencies from the NPM repository.

  2. In verify stage the gulp lint will run to lint the CSS source files using stylelint, and the JavaScript source files using eslint. If there is no code against the project style guide, the stage end successfully.

  3. Lastly, deploy stage will run gulp bundle and gulp preview:build to generate a distributable zip file with the UI project (the ui-bundle) and a preview site with de new UI. Both job contents will be archived as artifacts and can now be consumed by the main ArCo Playbook file.

Playbook file

To release a new version of the ArCo documentation site, we need to start a manual pipeline in the playbook project.

This pipeline has two stages:

  1. In the build stage the Antora site generator will be initiated from the official Antora Docker image.

    1. Before this script starts, the pipeline will download the latest bundled artifact of the ArCo UI bundle from the UI project using cURL. This artifact will be stored in a temporary folder and when finished, the main script will be executed.

    2. When the Antora site generator finishes, and the documentation site is now properly generated the pipeline will archive their contents in the project artifacts store for one week.

  2. A manual deploy stage can be started, and the public/ contents generated by the Antora site generator will be synced with the ArCo S3 web-hosting bucket.

The build pipeline should be automatically executed by a trigger or a schedule. This is a WIP.

Contributing

All changes pushed to the ArCo UI project, the ArCo Playbook or any component repository master branch can trigger a new release.

Therefore, you want to make your changes to a development branch and submit it as a pull request (PR/MR) to be approved. Only when the PR is approved and merged will the new release be triggered.

Use the following command to create a local development branch named feature/the-feature-name or hotfix/the-hotfix-name:

git checkout -b feature/the-feature-name -t origin/master

You’ll then apply your changes to the project and once you’re done making changes, commit those changes to the local branch:

git commit -a -m "describe your changes"

Then, push your branch to the remote repository:

git push origin feature/the-feature-name

Finally, navigate to the GitLab project in your browser and create a new pull request from this branch.

Another maintainer of the project should review the changes and if the changes are acceptable, the maintainer will merge the pull request.

As soon as the pull request is merged into master, an automated process will take over to publish a new release for the site generator to use.