Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added documentation for the documentation generator #83

Draft
wants to merge 9 commits into
base: main
Choose a base branch
from
Draft

Added documentation for the documentation generator #83

Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d3a591f
added documentation for the documentation generator
CMurtagh-LGTM Dec 12, 2020
5d56d56
Changed 1G to 1GB
CMurtagh-LGTM Dec 12, 2020
b0d30e9
Added Joey's suggestions
CMurtagh-LGTM Dec 12, 2020
7372da6
Changed default outdir directory name
CMurtagh-LGTM Dec 12, 2020
4334fcf
further propgation of name change
CMurtagh-LGTM Dec 12, 2020
38ef511
Merge branch 'master' into cmurtagh/NUdocDocumentation
CMurtagh-LGTM Feb 5, 2021
d9f50ed
fixed name
CMurtagh-LGTM Feb 5, 2021
2bb0bcb
Merge branch 'master' into cmurtagh/NUdocDocumentation
CMurtagh-LGTM Feb 12, 2021
8733ba0
Some grammar from Josephus
CMurtagh-LGTM Jul 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 24 additions & 13 deletions src/book/02-system/01-foundations/02-build-system.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,19 +109,20 @@ As is the case with modules and messages, utilities are grouped together into me

NUClear Roles introduces the `b` command that wraps up all of the functionality needed to create modules and build the NUbots code.

| Command | Description |
| --------- | -------------------------------------------------------------- |
| build | Build the currently configured code |
| configure | Configure the CMake system for the current target |
| edit | Edit configuration files |
| footdown | Trains a neural network to detect foot down based on leg loads |
| format | Applies code formatting rules to the codebase |
| install | Install built code to the specified robot |
| module | Generate new modules |
| nbs | For working with NBS recordings |
| run | Run a role locally |
| shell | Exposes a shell in the Docker image |
| target | Select a target to work on |
| Command | Description |
| ----------------- | --------------------------------------------------------------------------- |
| build | Build the currently configured code |
| configure | Configure the CMake system for the current target |
| edit | Edit configuration files |
| footdown | Trains a neural network to detect foot down based on leg loads |
| format | Applies code formatting rules to the codebase |
| install | Install built code to the specified robot |
| module | Generate new modules |
| nbs | For working with NBS recordings |
| run | Run a role locally |
| shell | Exposes a shell in the Docker image |
| target | Select a target to work on |
| extract-reactions | Dump documentation of each module's ons, emits and reactions in JSON format |
CMurtagh-LGTM marked this conversation as resolved.
Show resolved Hide resolved

##### Build

Expand Down Expand Up @@ -344,6 +345,16 @@ The `nuc7i7bnh` target should be used for building and running code on the robot

The `target` command will download (or, if needed, build) the Docker image for the specified target and then mark that target as active.

##### Extract-Reactions
CMurtagh-LGTM marked this conversation as resolved.
Show resolved Hide resolved

The `extract-reactions` command of `b` generates a JSON file documenting each Module. It lists each reactor, with their on statements and emit statements. The on and emit statements have their location in the file and their dsl worlds also.
CMurtagh-LGTM marked this conversation as resolved.
Show resolved Hide resolved

The `--indir` argument gives the root of the directories that will be documented, defaults to the `./module/` directory.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably best to make these arguments a table


The `--outdir` argument gives the directory that the JSON output will be written, defaults to `./doc/extract-documentation/` directory.

The `-m` or `--multiprocess` argument tells the command to use multiprocessing to greatly reduce the processing time, but uses a very large amount of RAM, about 1GB per thread.
CMurtagh-LGTM marked this conversation as resolved.
Show resolved Hide resolved

KipHamiltons marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you please add a guide for turning the output into a usable graph image or set of images? Do you recommend a JSON to dot converter which will work out of the box?
Also, a link to the clang API docs you used for reference would be nice.
In fact, a page about the tool, how it works, and how to use it wouldn't be a bad idea - something similar to the NUgan page.

Copy link
Member

@JosephusPaye JosephusPaye Jan 26, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The plan is to eventually extract the documentation, generate the images, and submit a PR to NUbook. Ideally automatically in CI when NUbots code changes.

The JSON here is custom, and I think Cameron has written something that does the conversion and generates an image.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@KipHamiltons Have you found any clang api docs? I haven't.
If you need to convert to DOT https://gist.github.com/ElderNoSpace/f0042e99b713601e0589a7692f6bff75
I don't think this tool warrants its own page.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here is a couple of links which would perhaps be useful? I'll let you be the judge of whether they give good insight into using the python bindings.
https://libclang.readthedocs.io/en/latest/
https://clang.llvm.org/doxygen/group__CINDEX.html
https://eli.thegreenplace.net/2011/07/03/parsing-c-in-python-with-clang

## Docker Images

The NUbots codebase uses Docker images to containerise the build process.
Expand Down