<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
Steve,<br>
<br>
<div class="moz-cite-prefix">Am 29.12.20 um 09:08 schrieb Stephen
Casner:<br>
</div>
<blockquote type="cite"
cite="mid:alpine.OSX.2.21.9999.2012281229460.98216@auge.attlocal.net">
<blockquote type="cite">
<pre class="moz-quote-pre" wrap=""> * 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.
</pre>
</blockquote>
<pre class="moz-quote-pre" wrap="">
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.</pre>
</blockquote>
<br>
That's nice now and should be sufficient.<br>
<br>
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.<br>
<br>
<br>
<blockquote type="cite"
cite="mid:alpine.OSX.2.21.9999.2012281229460.98216@auge.attlocal.net">
<blockquote type="cite">
<pre class="moz-quote-pre" wrap=""> * I think it's worth mentioning RegisterCommand() tolerates duplicate
registrations, allowing to forget about the init sequence.
* The cleanup scheme (command deregistration) is missing.
</pre>
</blockquote>
<pre class="moz-quote-pre" wrap="">
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?</pre>
</blockquote>
<br>
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:<br>
<ul>
<li>different core modules may add commands to shared roots (e.g.
"obdii" is shared now by the vehicle and obd2ecu modules)</li>
<li>unloadable modules (e.g. vehicles) need to deregister their
commands on unload</li>
</ul>
<br>
<blockquote type="cite"
cite="mid:alpine.OSX.2.21.9999.2012281229460.98216@auge.attlocal.net">
<blockquote type="cite">
<pre class="moz-quote-pre" wrap=""> * An explanation of the "execute" and "validate" handler signatures
probably also fits into the scope of this page.
</pre>
</blockquote>
<pre class="moz-quote-pre" wrap="">
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:
<a class="moz-txt-link-freetext" href="https://github.com/readthedocs/readthedocs.org/issues/2926">https://github.com/readthedocs/readthedocs.org/issues/2926</a>
Where there is a comment about how ESP-IDF documentation does this:
<a class="moz-txt-link-freetext" href="http://esp-idf.readthedocs.io/en/latest/contribute/documenting-code.html#linking-examples">http://esp-idf.readthedocs.io/en/latest/contribute/documenting-code.html#linking-examples</a>
And the code used to build the roles is here:
<a class="moz-txt-link-freetext" href="https://github.com/espressif/esp-idf/blob/master/docs/idf_extensions/link_roles.py">https://github.com/espressif/esp-idf/blob/master/docs/idf_extensions/link_roles.py</a></pre>
</blockquote>
<br>
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.<br>
<br>
With these you can reference the source files by relative paths.
Sphinx will automatically add all referenced files to the web
assets. Example:<br>
<br>
<font face="monospace">:download:`metrics.htm
<../dev/metrics.htm>` (hint: right click, save as)<br>
<br>
.. literalinclude:: ../dev/metrics.htm<br>
:language: html<br>
:linenos:<br>
</font><br>
→
<a class="moz-txt-link-freetext" href="https://docs.openvehicles.com/en/latest/components/ovms_webserver/docs/metrics.html">https://docs.openvehicles.com/en/latest/components/ovms_webserver/docs/metrics.html</a><br>
<br>
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.<br>
<br>
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.<br>
<br>
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:
<a class="moz-txt-link-freetext" href="https://docs.openvehicles.com/en/latest/userguide/scripting.html#pubsub">https://docs.openvehicles.com/en/latest/userguide/scripting.html#pubsub</a><br>
<br>
The "literalinclude" directive can be used to keep longer / full
examples along with the source code but still render them nicely in
the documentation.<br>
<br>
Regards,<br>
Michael<br>
<br>
<br>
<blockquote type="cite"
cite="mid:alpine.OSX.2.21.9999.2012281229460.98216@auge.attlocal.net">
<pre class="moz-quote-pre" wrap="">
-- Steve
_______________________________________________
OvmsDev mailing list
<a class="moz-txt-link-abbreviated" href="mailto:OvmsDev@lists.openvehicles.com">OvmsDev@lists.openvehicles.com</a>
<a class="moz-txt-link-freetext" href="http://lists.openvehicles.com/mailman/listinfo/ovmsdev">http://lists.openvehicles.com/mailman/listinfo/ovmsdev</a>
</pre>
</blockquote>
<br>
<pre class="moz-signature" cols="72">--
Michael Balzer * Helkenberger Weg 9 * D-58256 Ennepetal
Fon 02333 / 833 5735 * Handy 0176 / 206 989 26</pre>
</body>
</html>