Documentation guidelines#

Workflow#

Contributions to Autoware's documentation are welcome, and the same principles described in the contribution guidelines should be followed. Small, limited changes can be made by forking this repository and submitting a pull request, but larger changes should be discussed with the community and Autoware maintainers via GitHub Discussion first.

Examples of small changes include:

• Fixing spelling or grammatical mistakes
• Fixing broken links
• Making an addition to an existing, well-defined page, such as the Troubleshooting guide.

Examples of larger changes include:

• Adding new pages with a large amount of detail, such as a tutorial
• Re-organization of the existing documentation structure

Style guide#

You should refer to the Google developer documentation style guide as much as possible. Reading the Highlights page of that guide is recommended, but if not then the key points below should be noted.

• Use standard American English spelling and punctuation.
• Use sentence case for document titles and section headings.
• Use descriptive link text.
• Write short sentences that are easy to understand and translate.

Tips#

How to preview your modification#

There are two ways to preview your modification on a documentation website.

1. Using GitHub Actions workflow#

Follow the steps below.

1. Create a pull request to the repository.
2. Wait for the deploy-docs-pr check to finish. What happens next depends on where your branch is.
   • If your branch is in the repository itself, the publish-docs workflow publishes the preview a few minutes later. Then the github-actions bot adds a comment with the URL of the preview.
   • If your branch is in a fork, the site is built but not published. The github-actions bot adds a comment with a link to download the site, and the summary of the run explains how to view it on your computer.

If this is your first pull request to the repository, a maintainer must approve the workflows before they run.

2. Running a local server#

You can also build the documentation website on your local computer. This site uses Zensical. Most other Autoware repositories still use MkDocs.

To preview this site, install the dependencies of this repository in a virtual environment.

cd /PATH/TO/YOUR-autoware-documentation
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Then start the server.

zensical serve

Open http://127.0.0.1:8000/autoware-documentation/ to see the preview of the website.

To preview the documentation of another Autoware repository, install the shared MkDocs dependencies.

python3 -m pip install -U $(curl -fsSL https://raw.githubusercontent.com/autowarefoundation/autoware-github-actions/main/deploy-docs/mkdocs-requirements.txt)

Then run mkdocs serve in the directory of that repository, and open http://127.0.0.1:8000/.