Skip to content

Contribution Guidelines

Table of Contents

Introduction

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.

Project Folder Structure

The project structure is as follows:

Text Only
handbook/
├── docs/
│   ├── index.md
│   ├── local-submodule1/
│   │   ├── docs/
│   │   │   ├── index.md
│   │   │   ├── page1.md
│   │   │   └── page2.md
│   │   └── mkdocs.yml
│   ├── local-submodule2/
│   │   ├── docs/
│   │   │   ├── index.md
│   │   │   ├── page1.md
│   │   │   └── page2.md
│   │   └── mkdocs.yml
│   ├── index.md
│   ├── services.md
├── submodules/
│   ├── remote-submodule1/
│   ├── remote-submodule2/
├── mkdocs.yml
  • docs/: Contains all the documentation for the handbook.
  • The root docs/ directory contains the main documentation for the handbook.
  • docs/local-submodule*/: Contains the documentation for a specific service. Each service has its own directory that contains the documentation for that service.
  • submodules/: Contains the remote submodules for the handbook. Each remote submodule is a separate repository that contains its own documentation, e.g. Datatrail.
  • mkdocs.yml: The MkDocs configuration file It contains the navigation structure and other configuration options.
  • mkdocs.yml in root directory: Contains the configuration for the main Handbook website.
  • mkdocs.yml in submodules/ & docs/service/*: Contains the MkDocs configuration for the submodule that gets compiled into the Handbook. These only contain site_name and nav fields.
    • site_name: The name of the submodule (also used in the URL).
    • nav: The navigation structure for the documentation page for that submodule.

How to contribute

The Handbook compiles documentation from two sources:

1. Remote Submodules: These are separate repositories that contain their own documentation. Currently, the documentation for the following services is pulled from their respective repositories:

So, if you want to make changes to the documentation of any of the services listed above, go to the respective repository and make the changes there and the Handbook will automatically pull in the changes when it rebuilds.

Info

The Handbook rebuilds itself every day at midnight UTC.

If you want to trigger a rebuild manually, you can:

  • Manually run the docs Action on the Handbook Repository on GitHub.
  • Sending a repository_dispatch event to the chimefrb/handbook repository. See the Github Action Dispatch section for more details.

2. Local Submodules: These are directories within the Handbook repository (in docs/ folder) that contain their own documentation. If you want to make changes to the documentation of a local submodule, you can do so by following the steps below.

Editing from GitHub Website

Info

This method only works with local submodules. If you want to edit documentation from a remote repository, you need to go to the respective repository and make the changes there.

You can add/edit documentation directly from the GitHub website. Here's how you can do it:

  1. Go to the Handbook GitHub repository.
  2. Navigate to the docs/ directory.
  3. Click on the directory where you want to add/edit the documentation.
  4. Click on the Add file button and select Create new file or Upload files to add new documentation or edit existing documentation.
  5. After you have made the changes, scroll down to the Commit changes section.
  6. Add a commit message and an optional extended description.
  7. Click on the Commit changes button to commit your changes.
  8. Create a pull request to merge your changes into the main branch of the Handbook repository.

Editing from Local Development Environment

Setting up local development environment

To setup the Handbook on your machine, follow these steps:

Prerequisites: Python 3.9 (you can check this by running python --version in the terminal).

# Clone the handbook repositorygit clone https://github.com/chimefrb/handbook.git # Go to the handbook directorycd handbook# Pull the submodulesgit submodule update --init --recursive# Update the submodulesgit submodule update --recursive --remote# Install Poetrypip install poetry # Install the dependenciespoetry install # Run the prebuild scriptpoetry run prebuild # Serve the documentation locallymkdocs 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 documentation section

Adding documentation locally (local submodule)

If you want to add your service's documentation as a new section in the Handbook (i.e. a new local submodule), you can do so by following these steps:

  1. Create a new directory in the docs/ directory of the Handbook repository. The directory name should be the name of the service. For example, if you want to add documentation for a service called my-service, you need to create a directory called my-service in the docs/ directory.
  2. Create a new mkdocs.yml file in the my-service directory. The mkdocs.yml file should contain the following fields:
    YAML
    site_name: my-service # this is used in the URL, so keep it lowercase and use hyphens for spaces
nav:
  - Home: index.md 
  # Add more pages here
  3. Create a new index.md file in the my-service directory. This file will be the landing page for the service.

  4. Add the new local submodule to the mkdocs.yml file in the root directory of the Handbook. Add the following field to the nav section:

    YAML
    nav:
  - Home: index.md
  - My Service: "!include ./docs/my-service/mkdocs.yml"
    This will render a new section called My Service in the Handbook with the documentation from the my-service directory.

  5. Once you have added the new submodule, you can start adding new pages to the service by creating new Markdown files in the my-service directory.

  6. After you have made the changes, commit your changes using the following command:
    Bash
    git add .
cz commit
  7. Create a pull request to merge your changes into the main branch of the Handbook repository.

Adding documentation from a remote repository (remote submodule)

A remote submodule means that the documentation for your service exists in a separate repository.

Prerequisites:

Make sure your service's remote repository has:

  • A docs/ directory that contains the documentation.
  • A mkdocs.yml file in the root directory that contains the navigation structure for the documentation.
  • The site_name field should be the name of the service.
  • The nav field should contain the navigation structure for the documentation. See the MkDocs documentation for more information.

To make sure the Handbook can pull in the documentation from the remote repository, you need to add the remote repository as a Git submodule to the Handbook repository.

  1. Add the submodule to the submodules/ directory of the Handbook repository. You can do this by running the following command:

    Bash
    git submodule add <repository-url> submodules/<submodule-name>
    For example, to add my-service repository as a submodule run the following command:
    Bash
    git submodule add https://github.com/CHIMEFRB/my-service.git submodules/my-service

  2. Add the submodule to the mkdocs.yml file in the root directory of the Handbook. Add the following field to the nav section:

    YAML
    nav:
  - Home: index.md
  # ... other sections
  - My Service: "!include ./submodules/my-service/mkdocs.yml"
    This will render a new section called My Service in the Handbook with the documentation from the my-service remote repository.

Danger

If your remote repository generates the documentation from code (e.g. via Python docstrings using mkdocstrings), you need to make sure your package is installed in the environment where the Handbook is built. You can do this by adding the package to the poetry dependencies in the Handbook's pyproject.toml file.

If dependency conflicts arise, we recommend you add the documentation locally to the Handbook repository (via local submodules).

  1. After you have ensured that the Handbook is building successfully, commit your changes using the following commands:

    Bash
    git add .
cz commit

  2. Create a pull request to merge your changes into the main branch of the Handbook repository.

Now, the Handbook will automatically pull in the latest documentation from the remote repository everytime it rebuilds. This way, you can maintain your documentation in a separate repository and have it automatically aggregated into the Handbook.

Adding/Editing a page in a remote submodule

To add/edit a page in a remote submodule, you need to add/edit the page in the remote repository and then, if needed, add a reference to the page in the mkdocs.yml file of the remote repository.

Adding a page in an existing documentation section (local submodule)

To add a new page, create a new Markdown file in the docs/ directory of the respective local submodule and then add a reference to the file in the mkdocs.yml file.

For example, to add a new page called sample.md to the CHIME-FRB API docs, you need to do the following:

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

Now you need to add a reference to the sample.md file in the local submodule's mkdocs.yml file. Open the docs/chime-frb-api/mkdocs.yml file and add the following field to the nav section:

YAML
nav:
  # ... other sections
  - Sample: sample.md

This will render a new section called Sample in the CHIME-FRB API documentation page in the Handbook.

Editing a page in an existing documentation section (local submodule)

To edit a page, open the Markdown file in the docs/ directory of the respective local submodule and make the necessary changes. After you have made the changes, commit your changes using the following command:

Bash
git add path/to/changed/file
cz commit
You can then create a pull request to merge your changes into the main branch of the Handbook repository.

How to enable comments on a page

If you want to enable comments on a page, you can do so by adding the following line at the start of the Markdown file:

Markdown
---
comments: true
---
This will enable comments on the page. Users can leave comments by scrolling to the bottom of the page and interacting with the comment section, powered by GitHub.

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@v3
        with:
          token: ${{ secrets.BUILD_HANDBOOK_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.

If you need any help, please reach out to the Project Office.

Comments