Common Documentation

Documentation partials and JSON variables for generating sweet READMEs and templated files for hundreds of repositories

Table of Contents

• ➤ Summary
• ➤ Repository Types
• ➤ Requirements
• ➤ Flow Summary
• ➤ common.json

Summary

In all of our projects, we strive to maintain useful and informative documentation. However, with hundreds of projects and limited man power, it can be tricky. To solve this problem, we re-use documentation partials to generate the documentation in each of our repositories.

There are two repositories responsible for generating the documentation for each project:

1. Shared documentation repository: This repository contains documentation partials that are used throughout all of our repositories.
2. Project-type documentation repository: This repository is where we store documentation that is specific to the type of project that downstream repository is. For example, if the downstream project is an Ansible role, then the repositories that will be used to generate the documentation will be the shared documentation repository and the Ansible documentation repository.

Repository Types

We currently use this method to scaffold our projects of the following types:

1. Angular
2. Ansible
3. Dockerfile
4. Go
5. NPM
6. Packer
7. Python

Repository Pipeline Order

Whenever a change is made to the shared documentation repository, the pipeline for the project-specific repositories will trigger (unless it is configured not to do so). Part of that pipeline includes cloning the shared documentation repository into the project-specific repository. When this happens, the common/ folder in the shared repository is copied over to the project-specific repository.

After the common/ folder is copied over, the project-specific repository will trigger the pipeline for the project-specific common files repository (e.g. Ansible common files repository). When this is happens, the project-specific documentation repository is added to the project-specific common files repository in the docs/ folder.

Finally, after the project-specific common files repository is up-to-date, the files it contains are propagated out to the individual projects that all of these repositories are for. This whole process allows us to update, say, a spelling error in the documentation to every project in our eco-system without an repetition.

Flow Summary

To summarize, the order of the flow is:

1. Shared documentation repository
2. Project-specific documentation repository (e.g. Ansible documentation)
3. Project-specific common files repository (e.g. Ansible common files)
4. Individual project repository (e.g. Ansible role for Android Studio)

So, with synchronization turned on, a change to the shared documentation repository would trigger updates for the most repositories since it is the highest upstream repository.

common.json

In both the shared documentation repository and the project-specific documentation repositories there is a file called common.json in the root of the projects. These files contain variables that are used to dynamically inject variables into the documentation and other files. The common.json files in both repositories are merged when there are updates to create the variables.json file that is in each project-specific documentation repository. During this process, the variables in the project-specific common.json file takes precedence over the variables in the shared common.json file. There are a few other steps that are made to create the final version of the .variables.json that each project uses to generate documentation and other files. In order of precedence, the variables are acquired from:

1. The variables in the "blueprint" section of the package.json file that is located in each downstream project
2. The variables stored in the common.{{ project_subgroup }}.json file stored in the common files repository for each project type (e.g. the Android Studio Ansible project uses the common.role.json file in the Ansible common files repository since the project subtype is a role)
3. The common.json file in the project-type-specific documentation repository (e.g. for the Android Studio Ansible role this would be the Ansible documentation repository)
4. The common.json file in the shared documentation repository