Skip to content

Contribution Guidelines

Handbook aims to be a community driven project. We welcome all contributions, big or small. If you are interested in contributing, please read the following guidelines.

Handbook uses Material for Mkdocs as the engine for generating the documentation. All of the documentation is written in Markdown. Checkout the Basic Syntax for Markdown and Material for Mkdocs Reference Guide to see what is possible.

How to contribute

You can contribute to the Handbook in the following ways:

Editing from GitHub Website

Work in progress...

Editing from Local Development Environment

Setting up local development environment

To setup the development environment, you need to install the following:

# Install poetrypip install --upgrade poetry# Clone the handbook repositorygit clone https://github.com/chimefrb/handbook.git # (1)# Go to the handbook directorycd handbook# Install the dependenciespoetry install# Activate the virtual environmentpoetry shellpre-commit install # (2)
mkdocs serve

Info

Now you can open the documentation in your browser by going to http://127.0.0.1:8000/handbook/

After you make changes to the documentation, you can commit your changes using the following command:

git add path/to/changed/file# Commit your changes with commitizencz commit

Note

The cz command is an alias for commitizen. It is a tool for writing conventional commits. We use it to enforce a consistent commit message format.

Adding a new page

To add a new page, create a new Markdown file in the docs directory and then add a reference to the file in the mkdocs.yml file. The mkdocs.yml file is the configuration file for the documentation. It contains the navigation structure and other configuration options.

For example, to add a new page called sample.md to the documentation website, you need to do the following:

# Create a new file called `sample.md` in the `docs` directory.touch docs/sample.md# Add some content to the file.echo "# Sample Page" >> docs/sample.md

Now you need to add a reference to the sample.md file in the mkdocs.yml file. Open the mkdocs.yml file and add the following to the nav section:

YAML
nav:
  - Home: index.md
  - Sample: sample.md

This will render a new section called Sample in the navigation bar. The Sample section will contain a link to the sample.md page.

Adding existing Mkdocs Documentation from another repository

We use the mkdocs-multirepo-plugin to add existing Mkdocs documentation from another repository. To add a new repository, add the following to the mkdocs.yml file:

YAML
nav:
  - Home: index.md
  - Sample: sample.md
  - Technical:
    - 'Some Other Repository': '!import https://github.com/chimefrb/some-other-repo?branch=main'

Note

The !import tag is used to import the documentation from another repository. The branch parameter is optional. If you don't specify the branch parameter, then the master branch will be used.

Adding a single markdown file from another repository

To add a single markdown file from another repository, you need to add two sections to the mkdocs.yml file. The first section is the plugins section. This section contains the configuration for the mkdocs-multirepo-plugin. The second section is the nav section. This section contains the navigation structure for the documentation.

YAML
plugins:
  - multirepo:
      nav_repos:
        - name: baseband-analysis # (1)
          import_url: "https://github.com/chimefrb/baseband-analysis?branch=main" # (2)
          imports: ["docs/docker.md", "docs/beamforming.md"] # (3)
  1. The name field becomes the prefix of the path for the imported files in the nav section. For example, if the name is baseband-analysis, then the path for the imported files will be /baseband-analysis/docs/docker.md and /baseband-analysis/docs/beamforming.md.
  2. The git repository that contains the markdown files to be imported.
  3. The list of markdown files to be imported.
YAML
nav:
  - Home: index.md
  - Sample: sample.md
  - Technical:
      - docker: /baseband-analysis/docs/docker.md # (1)
  1. The path to the imported markdown file. The path is relative to the name field in the plugins section.

Github Action Dispatch

As a developer whose documentation is aggregated into the handbook, you can automatically trigger the Github Action to rebuild and deploy an updated version of the handbook. This is very useful, especially when documentation from a lot of sources is aggregated into the handbook and you don't want to wait for the maintainers to trigger an update to reflect your changes.

Ideally, you should trigger a rebuild from when you merge changes into the main branch of your repository. To do so, you need to add the following to your Github Actions workflow file:

Info

To trigger the Github Action, you need to send a repository_dispatch event to the chimefrb/handbook repository. The repository_dispatch event is a custom event that you can send to any repository. You can read more about it here.

YAML
# .github/workflows/trigger-handbook-build.yml

name: Build trigger for chimefrb/handbook

on:
  push: # (1)
    branches:
      - main
  path:
    - 'docs/**' # (2)
    - 'path/to/changed/file/markdown.md' # (3)
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - 
        name: Build chimefrb/handbook 
        uses: peter-evans/repository-dispatch@v2
        with:
          token: ${{ secrets.CHIMEFRB_BOT_TOKEN }}
          repository: chimefrb/handbook
          event-type: build-handbook
          client-payload: '{"source": "chimefrb/<YOUR-REPO-NAME>"}'
  1. The push event is triggered when you push changes to the main branch of your repository.
  2. The path filter is used to trigger the workflow only when changes are made to the docs directory.
  3. The path filter is used to trigger the workflow only when changes are made to the path/to/changed/file/markdown.md file.