Autoware.Auto
|
|
The Autoware.Auto documentation is created with the doxygen
tool based on text files written in markdown; see markdown in doxygen for details.
Verify the documentation builds without errors and appears as desired by building locally first:
docs/.doxygen/build.py
At the end of the long output of this command, the entry point is displayed. Open in a web browser
Documentation has been built in: /home/user/AutowareAuto/docs/_build/html/index.html
As a final check before merging, validate that the documentation built in CI is correct by browsing the artifacts of the docs stage of the merge request's build job. The URL will be similar to the following but the build job ID has to be modified
To select the docs with a mouse, first open the pipeline of the merge request on GitLab, then select the docs job:
Finally browse the artifact and select the html file(s) modified in the merge request.
Lines in markdown shall in general be limited to 100 characters with exceptions when that's impractical; e.g.
To ease code review, it is recommended that each sentence start on a new line. This doesn't break paragraphs unless a blank line is included.
Start a fenced code block and add the language (cpp, py, bash, xml
...) for syntax highlighting in braces; e.g.,
```{cpp} int main() { return 0; } ```
Illustrations and screenshots are great to make a point and can save a lot of text. Place an image into the docs/images
folder and refer to it as
@image html images/foo.png "image caption"
This way of including ensures that doxygen fails if it cannot find the image. Optionally, one can set e.g. the width of the image in the output in absolute or relative size to prevent a large image from disrupting the reading flow:
@image html images/foo.png "image caption" width=1000px @image html images/foo.png "image caption" width=50%
Add an anchor for a new document; e.g.
#new-document
After the title and use the anchor to link to other parts of the documentation. A minimal example:
And within another foo.md
, refer to the new document with:
Make sure the document is included by an appropriate index.md
such that it appears at the desired location; e.g.,
Documents that link to a section in the doxygen output also need an anchor for that URL to be stable with respect to documentation updates. To that end, the anchor should have a prefix that's unique to the page in which the section lives.
Recommended
Inside document.md
:
Then the URL is https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/document.html#document-foo
Discouraged
Inside document.md
:
Then the URL could be e.g. https://autowarefoundation.gitlab.io/autoware.auto/AutowareAuto/document.html#autotoc_md21
Notice the autotoc_md21
at the end of the URL. Doxygen increments a counter to automatically create URLs for sections without an anchor. If the section Foo
is moved or another section added somewhere else, the URL may become invalid.
Packages shall be accompanied with a design document written in markdown; e.g. in pkg_foo/design/pkg_foo-design.md
. There can be several files in design/
if needed. The purpose of the design document is to describe the intended behavior of a component. Serving as an entry point for users unfamiliar with that component, it should explain at a sufficient abstraction level.
All C++ code that is to be consumed by someone else should be declared in header files and should come with doxygen comments including classes, structs, methods, members etc.
Use the imperative to describe each entity. Finish each section with a period .
.
For example:
Add comments where the code is not self-explanatory. When adding comments, think about renaming/restructuring to make the code self-explanatory.
Don't add this comment as it doesn't provide useful information