[Ovmsdev] Addition to OVMS Developer Guide

[Michael Balzer]

Steve,

Am 29.12.20 um 09:08 schrieb Stephen Casner:
>>   * 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.

That's nice now and should be sufficient.

There certainly are commands that don't need explanations, but let me 
pick an example that evolved into the opposite: "metrics list" 
originally didn't need an explanation. Then the parameter "[<metric>]" 
was added, which already isn't self-explaining, as a user will interpret 
it to be a full metric name, but it actually is a substring to match the 
metric names against. With "[-ps]" we finally crossed the border of "you 
need to read the source code to know what this does". It isn't even 
clear from the usage template that "p" and "s" are separate options.


>>   * 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?

No, we'll add that to the scripting API sections when the feature is 
available. This section should focus on the C++ API, and I meant the C++ 
side as well:

  * different core modules may add commands to shared roots (e.g.
    "obdii" is shared now by the vehicle and obd2ecu modules)
  * unloadable modules (e.g. vehicles) need to deregister their commands
    on unload


>>   * 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

I had a similar problem with the web plugin examples & documentation 
pages. I used a combination of :download: and .. literalinclude:: 
instead of links to the sources.

With these you can reference the source files by relative paths. Sphinx 
will automatically add all referenced files to the web assets. Example:

:download:`metrics.htm <../dev/metrics.htm>` (hint: right click, save as)

.. literalinclude:: ../dev/metrics.htm
    :language: html
    :linenos:

→ 
https://docs.openvehicles.com/en/latest/components/ovms_webserver/docs/metrics.html

Mark prepared the component directories for inclusion in the sphinx tree 
by a simple symlink (docs/source/components), to cover the "main" 
modules as well we can simply add another symlink.

This does not cover plain links to the source files on github however. 
You can try adapting the custom link roles from the ESP-IDF for this.

I personally think we should avoid linking to the source code from the 
documentation. A developer won't need that link, more appropriate is 
including condensed example snippets. We did so on the scripting API 
sections, for example: 
https://docs.openvehicles.com/en/latest/userguide/scripting.html#pubsub

The "literalinclude" directive can be used to keep longer / full 
examples along with the source code but still render them nicely in the 
documentation.

Regards,
Michael


>
>                                                          -- Steve
> _______________________________________________
> OvmsDev mailing list
> OvmsDev at lists.openvehicles.com
> http://lists.openvehicles.com/mailman/listinfo/ovmsdev

-- 
Michael Balzer * Helkenberger Weg 9 * D-58256 Ennepetal
Fon 02333 / 833 5735 * Handy 0176 / 206 989 26

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openvehicles.com/pipermail/ovmsdev/attachments/20201229/b77586c5/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_signature
Type: application/pgp-signature
Size: 203 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openvehicles.com/pipermail/ovmsdev/attachments/20201229/b77586c5/attachment-0001.sig>