Skip to content

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.

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. Add the deploy-docs label from the sidebar (See below figure).
  3. Wait for a couple of minutes, and the github-actions bot will notify the URL for the pull request's preview.

deploy-docs-label

2. Running an MkDocs server in your local environment#

Instead of creating a PR, you can use the mkdocs command to build Autoware's documentation websites on your local computer. Assuming that you are using Ubuntu OS, run the following to install the required libraries.

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 on your documentation directory.

cd /PATH/TO/YOUR-autoware-documentation
mkdocs serve

It will launch the MkDocs server. Access http://127.0.0.1:8000/ to see the preview of the website.