[Ovmsdev] Addition to OVMS Developer Guide

[Stephen Casner]

Michael,

> thanks, looks good. Instead of removing the section from the Google doc, I
> suggest replacing it by a link to the RTD page.

Well, replacing it by a link would remove it, no?  But I think perhaps
what you meant is to add a link.  I've done that.

>  * Please check for typos and grammar.

I found four errors, "to add ... are added", "Regiser", "the this" and
"An variant".  I consider myself a stickler for grammar so if you find
other places to be problematic, please identify them specifically.
Also I may tend to construct longer sentences than some editors would
favor, so I have also tried to do a bit of wordsmithing.

>  * I opt to change the side note "explanatory text can be included"
>    into a strong recommendation, as we still have many commands that
>    lack explanations, and we should avoid the impression of that being
>    the accepted standard. Users shall gain confidence about using a
>    command by reading the command's usage info.

I don't think we need additional explanatory lines on all our
commands, but I take your point.  I've added a Note about this after
the paragraph where the "usage" argument is introduced.

>  * I think it's worth mentioning RegisterCommand() tolerates duplicate
>    registrations, allowing to forget about the init sequence.
>  * The cleanup scheme (command deregistration) is missing.

Aha, my perspective has been from the C++ code.  These comments are
relevant to scripting, which is beyond my ken at this point.  I've
added a subsection and "TBA" where this discussion could go.  Beyond
the two points you mention, I think it may need part of the writeup
you did for Mark when explaining how to manage this.  Would you want
to add that?

>  * An explanation of the "execute" and "validate" handler signatures
>    probably also fits into the scope of this page.

Yes, since the developer will need to create them.  I've added some
explanations of the signatures and what the functions should do.

Is there a clean way to put in references to source files?  I could
form an HTTP URL referencing the raw file in github, but that is
unreliable.  Google found this on the topic:

https://github.com/readthedocs/readthedocs.org/issues/2926

Where there is a comment about how ESP-IDF documentation does this:

http://esp-idf.readthedocs.io/en/latest/contribute/documenting-code.html#linking-examples

And the code used to build the roles is here:

https://github.com/espressif/esp-idf/blob/master/docs/idf_extensions/link_roles.py

                                                        -- Steve