[Ovmsdev] Addition to OVMS Developer Guide

[Michael Balzer]

Steve,

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

Content suggestions:

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

Regards,
Michael


Am 28.12.20 um 03:59 schrieb Stephen Casner:
> 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 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
>>> _______________________________________________
>>> 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
>>
>>
> >
>
> _______________________________________________
> 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/20201228/ede5e22f/attachment.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/20201228/ede5e22f/attachment.sig>