[Ovmsdev] Documentation

[Mark Webb-Johnson]

The google doc user guide we have is really not working out. Not searchable, not indexed anywhere, not friendly for the end-user, and hard to maintain as a team.

So, we’ve setup a readthedocs repository for documentation, and adopted the Sphinx ‘docs’ standard for documentation. The User and Vehicle guides have been ported over to this new system, and are live now:

https://docs.openvehicles.com/ <https://docs.openvehicles.com/>

The way the system works is that documentation is written in reStructuredText (rst) format, stored in ‘docs’ directories in our main code github repository, and processed by the Sphinx documentation system to produce HTML, PDF, ePub, etc documentation. I’ve created a top-level ‘docs’ directory, as well as individual ‘docs’ directories in each of the vehicle support components. That way, each vehicle developer has control over their own vehicle documentation, and it all gets compiled and made available online automatically. Documentation changes are incorporated in exactly the same way as code changes - by github pull requests - and you can keep your documentation up to date with the code. Screenshots and other images can simple be loaded into the ‘docs’ directory and displayed inline using reStructuredText directives. A good introduction to the available markup directives is here:

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>

There are also lots of examples in the documentation we have already produced.

When we commit to github, a trigger fires and notifies the readthedocs service that we have changed. That service then rebuilds the documentation (usually within a few seconds, or a minute at most), and makes it available as html, pdf, ePub, etc. It also supports version control (using github release tags), and language translations.

If you are doing a lot of work on documentation, you can install the sphinx tools locally (I simply use 'pip install sphinx'), and ‘make html’ to build documentation locally (then view it in your web browser as a local set of files).

So far, the user and vehicle guides have been ported over pretty much ‘as is’, without changes. We can now work on improving them, and trying to come up with a quickstart type of installation guide to cover the basics, with advanced topics available for the more adventurous.

The next step will be to address the developer documentation. We should be able to include this inline with the code, and have Sphinx extract the classes and methods automatically to build developer guides.

Regards, Mark.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openvehicles.com/pipermail/ovmsdev/attachments/20190705/55230997/attachment.html>