Added documentation for the documentation generator #83
Conversation
Co-authored-by: Josephus Paye II <[email protected]>
| 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. | ||
|
|
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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
|
Wait .... The documentation generator doesn't generate its own documentation???? Missed opportunity |
|
|
||
| The `extract-documentation` 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. | ||
|
|
||
| The `--indir` argument gives the root of the directories that will be documented, defaults to the `./module/` directory. |
There was a problem hiding this comment.
Probably best to make these arguments a table
Co-authored-by: Josephus Paye II <[email protected]>
Some documentation for the new
./bdocumentation generation script.