<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
Steve,<br>
<br>
thanks, looks good. Instead of removing the section from the Google
doc, I suggest replacing it by a link to the RTD page.<br>
<br>
Content suggestions:<br>
<ul>
<li>Please check for typos and grammar.</li>
<li>I think it's worth mentioning RegisterCommand() tolerates
duplicate registrations, allowing to forget about the init
sequence.</li>
<li> 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.</li>
<li>The cleanup scheme (command deregistration) is missing.<br>
</li>
<li>An explanation of the "execute" and "validate" handler
signatures probably also fits into the scope of this page.</li>
</ul>
Regards,<br>
Michael<br>
<br>
<br>
<div class="moz-cite-prefix">Am 28.12.20 um 03:59 schrieb Stephen
Casner:<br>
</div>
<blockquote type="cite"
cite="mid:alpine.OSX.2.21.9999.2012271850420.85432@auge.attlocal.net">
<pre class="moz-quote-pre" wrap="">Michael,
OK, I converted my CLI documentation from the Google Doc into Sphinx.
I added it at the top of the list of Developer Guides since the CLI is
one of the first points of interaction for a developer (after the web
installation wizard and configuration), but feel free to move it
somewhere else that might be more appropriate.
There may be markup conventions to adjust.
I'm inclined to delete this section from the Google Doc now to avoid
having changes diverge. Would you (and Mark) agree?
I started with an automated conversion from the Google Doc source to
rST markup, then manually cleaned it up. It wasn't too hard. Maybe
that process could be use to move over the remained of the Google
Doc.
-- Steve
On Sun, 27 Dec 2020, Michael Balzer wrote:
</pre>
<blockquote type="cite">
<pre class="moz-quote-pre" wrap="">Steve,
yes, we're in the long-term migration of the developer documentation to
Sphinx.
→ <a class="moz-txt-link-freetext" href="http://lists.openvehicles.com/pipermail/ovmsdev/2019-July/006196.html">http://lists.openvehicles.com/pipermail/ovmsdev/2019-July/006196.html</a>
The Google document still serves as an introduction for new firmware and
hardware developers. New parts have been added to sphinx, but existing
sections haven't been transformed yet. The parts in Sphinx are currently more
targeted towards developers using the system, but just because they've been
added after we decided to move to Sphinx.
Regards,
Michael
Am 26.12.20 um 22:42 schrieb Stephen Casner:
</pre>
<blockquote type="cite">
<pre class="moz-quote-pre" wrap="">Michael,
The documentation I added was in the Google Doc OVMS Developer Guide:
<a class="moz-txt-link-freetext" href="https://docs.google.com/document/d/1q5M9Lb5jzQhJzPMnkMKwy4Es5YK12ACQejX_NWEixr0/">https://docs.google.com/document/d/1q5M9Lb5jzQhJzPMnkMKwy4Es5YK12ACQejX_NWEixr0/</a>
Is that document supposed to be replaced by the github-based
Sphinx/RTD documentation that you mention? The Google Doc appears
quite unfinished in that there are many blank pages between sections
and the TOC is not updated.
-- Steve
On Tue, 22 Dec 2020, Michael Balzer wrote:
</pre>
<blockquote type="cite">
<pre class="moz-quote-pre" wrap="">Thanks, Steve.
That reminds me of looking for a solution to generate RTD pages from the
C++
sources, e.g. by sphinx-autodoc or similar. I prefer looking into the
source,
but have to admit the API documentation of the esp-idf is usable. We
probably
need to restructure most existing method & class comments and add the
missing
ones, but maintaining the API documentation would be easy afterwards.
Regards,
Michael
Am 22.12.20 um 09:14 schrieb Stephen Casner:
</pre>
<blockquote type="cite">
<pre class="moz-quote-pre" wrap="">At Mark's request I have added a description of how to add commands to
the console command interpreter including the usage string syntax.
This should be considered a draft at this point; questions and
comments are welcome.
I added this under Vehicle Firmware Overview, but that might not be
the right place. There is no general description of the core
firmware.
-- 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>
<pre class="moz-quote-pre" wrap="">--
Michael Balzer * Helkenberger Weg 9 * D-58256 Ennepetal
Fon 02333 / 833 5735 * Handy 0176 / 206 989 26
</pre>
</blockquote>
<pre class="moz-quote-pre" wrap="">_______________________________________________
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>
<pre class="moz-quote-pre" wrap="">
--
Michael Balzer * Helkenberger Weg 9 * D-58256 Ennepetal
Fon 02333 / 833 5735 * Handy 0176 / 206 989 26
</pre>
</blockquote>
<pre class="moz-quote-pre" wrap="">></pre>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<pre class="moz-quote-pre" wrap="">_______________________________________________
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>