Better documentation

[ottopasuuna]

Currenty the only thing that is documented sufficiently is the ExampleProcess.py. The rest of the code base relies on descriptive variable names, which is fine for small programs, but our sofware has grown enough in the past few years that more rigerous documentation will make it easier for new members to learn the internals, and improve the longevity of the project. Also, I don't think anyone really goes to the wiki, nor updates it, so finding a different place (ReadTheDocs?) to put all our documentation for roveberrypy, embeded code, PCBs, and how to get started with the team, might be a good idea.

• [x] Autogenerated docs with sphinx

• [ ] Add docstrings

  • [x] RoverProcess
  • [x] USBServer
  • [x] RoverServer
  • [x] StateManager
  • [ ] DriveProcess
  • [ ] ArmProcess
  • [ ] DrillProcess

• [x] Tutorial on adding a rover process

  • [x] Add new rover process
  • [x] Messaging
  • [x] Documenting

• [x] Get it on ReadTheDocs

• [x] Create USST Github page that leads to documentation pages for other repos.

• [ ] Embeded documentation

  • [x] Tutorials
  • [ ] Doxygen autodocs?

• [x] Tutorial on how to wire up and assemble the rover

• [x] Tutorial on how to run/operate the rover.

• [x] Info on how to contribute to the team.

[climathosphere]

I Second This.

[ottopasuuna]

I was just looking at Github pages, and they look like a possible solution. We could use ReadtheDocs/sphinx for autogenerating documentation from code coments, and have examples on how to use the software in that repo. Then a Github page for the usst organization could act as a hub linking to all the individual repo's doc pages, and explaining how things work together, as well as general team contributing stuff such as git tutorials etc.

[ottopasuuna]

I think I got a solution for the central docs page. I have a heroku app watch pushes to the private branch on the uofsspacedesignteam.github.io repo, and it uses a script called jekyll-auth to only allow people in our github organization to view the page. Try it out here https://usstdocs.herokuapp.com/

[ottopasuuna]

Docs are basically done for now, in the future I would like to add Doxygen for the embedded stuff, but there isn't much to document, and I'd rather save the effort for next year's API's.