I made a python script to generate VEX controller documentation automatically from PROS source code

Programming Support PROS Support
,
#1

Check out this GitHub repository to see the python script and some more information about how to set up and use it in your own project. I tested this on Ubuntu 18.04 and macOS Catalina 10.15.5.

This python script parses a “constants.h” file with button assignments of the form

const auto INTAKE_BUTTON  = okapi::ControllerDigital::R1;

to generate a markdown file of button assignments.

Motivation

This script is useful particularly when any of the following are true:

  • the drivers are not involved in programming the robot
  • there are multiple drivers for each robot
  • two robots have different button assignments, and it is desired to have a readily available reference for button bindings for each robot (i.e. for VEX U teams)

Setup

Setting up your project structure to use the parse_key_bindings script is also pretty straightforward

  • Create a directory called docs in your top level directory, and put the file controller.png in this directory.
  • Create a file called constants.h and assign your button mappings inside of it (see constants_example.h).
  • Add the lines builddocs: path/to/constants.h, and python generic_parse_key_bindings.py to the beginning of your Makefile, which is in the top level directory of your project folder (see Makefile_example).
  • Update parse_key_bindings.py with the requested information

Usage

To generate the documentation, type prosv5 make builddocs at the root directory of your project. If you want the script to be run everytime you compile the project, you can create aliases in your .bashrc (or equivalently .zshrc, etc): alias pm='prosv5 make builddocs', alias pmu='pm && prosv5 upload', and alias pmut='pmu && prosv5 terminal'.

Example of project that uses this script

See this github repository for an example of all the above used in a PROS project.

14 Likes
#2

Why not just use Doxygen for this?

5 Likes
#3

I don’t have much experience with Doxygen actually. This seemed to me like a nice way to get the drivers, programmers, and whoever else on the same page with relatively low effort from all parties and so I thought I’d share it with the community. That said, I’ll look into Doxygen. Thanks for the suggestion.

4 Likes