• Please check for typos and grammar.
• I think it's worth mentioning RegisterCommand() tolerates duplicate registrations, allowing to forget about the init sequence.
• 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.
• The cleanup scheme (command deregistration) is missing.
  
• An explanation of the "execute" and "validate" handler signatures probably also fits into the scope of this page.

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:

Steve,

yes, we're in the long-term migration of the developer documentation to
Sphinx.

→ http://lists.openvehicles.com/pipermail/ovmsdev/2019-July/006196.html

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:

Michael,

The documentation I added was in the Google Doc OVMS Developer Guide:

https://docs.google.com/document/d/1q5M9Lb5jzQhJzPMnkMKwy4Es5YK12ACQejX_NWEixr0/

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:

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:

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
OvmsDev@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

_______________________________________________
OvmsDev mailing list
OvmsDev@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

>

_______________________________________________
OvmsDev mailing list
OvmsDev@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