Documentation

What?

Documentation helps new users and developers to understand how to use this project.

Why?

We want to be able to share this project with other villages so that they have an easier time making great content. This will also help us speed up on boarding and development internally.

How?

Code documentation

For code documentation we will be using doxygen style comments. Doxygen is a very common and easy to use documentation style which can easily generate developer docs in html or pdfs.

Code Documentation TODOs:

/

• addAdmin.py
• addDevice.py
• addDeviceType.py
• changePassword.py
• rmDevice.py
• setup.py

HardwareCheckout/

• init.py
• main.py
• auth.py
• config.py
• device.py
• main.py
• models.py
• queue.py
• terminals.py
• user.py
• webutil.py

tmate/

• connected.py
• create_config.py
• device.py
• deprovision.sh
• autologout.sh
• install.sh
• provision.sh
• session.sh
• session_restart.sh

Functional/User guides

I don't have a preference for these, but markdown is easy to write and integrates well with github. We are open to suggestions, but all the documentation needs to be in the same format.

Functional/User guides TODOs

• Project overview readme - This will be the toplevel read me and overview of the project. It will need a high level descriptions of getting started and where to look for more documentation. (This may need to be done last).
• Production setup guide - This will be the steps to take to go from a clean ubuntu install to a running production ready installation. Make sure to include steps to enable SSL or run it without.
• Hardware setup guide - This is the guide to getting everything setup on the Raspberry Pis that are connected to the cars. This only talks about code which we made for this project. Since this may be used by other villages, it doesn't make sense to include car hacking village specific things, like installation of CAN Bus tools.
• Developer contribution guide - This one talks about what we expect from people contributing to our projects. Specifically mention that we use doxygen style commenting and pull requests.
• Administration guide - This one talks about how to work with the server once it is running.

Start by selecting one file or guide from the listed TODOs, such as a Python module under HardwareCheckout/ or the production setup guide. Read the selected file and its surrounding project context first. Done means documenting the selected code with Doxygen-style comments or completing the selected Markdown guide, rather than addressing the entire checklist.