Contribution Guidelines¶
Table of Contents¶
- Contribution Guidelines
- Table of Contents
- Introduction
- Project Folder Structure
- How to contribute
- Editing from GitHub Website
- Editing from Local Development Environment
- Setting up local development environment
- Adding a new documentation section
- Adding documentation locally (local submodule)
- Adding documentation from a remote repository (remote submodule)
- Adding/Editing a page in a remote submodule
- Adding a page in an existing documentation section (local submodule)
- Editing a page in an existing documentation section (local submodule)
- How to enable comments on a page
- Github Action Dispatch
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:
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-repo1/
│ ├── remote-repo2/
├── 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
insubmodules/
&docs/service/*
: Contains the MkDocs configuration for the submodule that gets compiled into the Handbook. These only containsite_name
andnav
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 thechimefrb/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.
- Go to the Handbook GitHub repository and add or edit the documentation directly from the GitHub website.
- Clone the repository to your local machine and setup a local development environment. See the Setting up local development environment section for more details.
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:
- Go to the Handbook GitHub repository.
- Navigate to the
docs/
directory. - Click on the directory where you want to add/edit the documentation.
- Click on the
Add file
button and selectCreate new file
orUpload files
to add new documentation or edit existing documentation. - After you have made the changes, scroll down to the
Commit changes
section. - Add a commit message and an optional extended description.
- Click on the
Commit changes
button to commit your changes. - 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).
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:
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:
- 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 calledmy-service
, you need to create a directory calledmy-service
in thedocs/
directory. - Create a new
mkdocs.yml
file in themy-service
directory. Themkdocs.yml
file should contain the following fields: - Create a new
index.md
file in themy-service
directory. This file will be the landing page for the service. -
Add the new local submodule to the
This will render a new section calledmkdocs.yml
file in the root directory of the Handbook. Add the following field to thenav
section:My Service
in the Handbook with the documentation from themy-service
directory. -
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. - After you have made the changes, commit your changes using the following command:
- 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.
-
Add the submodule to the
For example, to addsubmodules/
directory of the Handbook repository. You can do this by running the following command:my-service
repository as a submodule run the following command: -
Add the submodule to the
mkdocs.yml
file in the root directory of the Handbook. Add the following field to thenav
section:YAMLThis will render a new section callednav: - Home: index.md # ... other sections - My Service: "!include ./submodules/my-service/mkdocs.yml"
My Service
in the Handbook with the documentation from themy-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).
-
After you have ensured that the Handbook is building successfully, commit your changes using the following commands:
-
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:
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:
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:
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:
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.
# .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>"}'
- The
push
event is triggered when you push changes to themain
branch of your repository. - The
path
filter is used to trigger the workflow only when changes are made to thedocs
directory. - The
path
filter is used to trigger the workflow only when changes are made to thepath/to/changed/file/markdown.md
file.
If you need any help, please reach out to the Project Office.