Open mathisloge opened 3 years ago
It might be also an option to specify eg. --icd latex
or --icd asciidoc
etc. to get a different output format. (or --icd custom
which should be a path to a file which contains a template.)
All outputs will be templates where defined keywords will be replaced with the protocol definitions
Hi Mathis, I don't exactly understand what you mean by ICD, but I have had a long term plan to implement automatic protocol specification generated out of schema files. Unfortunately I didn't come around to actually design and implement such tool. You're more than welcome to do it yourself. However, there are a few things I want you to consider.
commsdsl2comms
application, even though it contains a convenient functionality of using template strings and substituting parts of it. The documentation generation functionality is really an iceberg, the hidden part of which is very easy to underestimate. For example, you'll probably eventually need an extra documentation snippets injection functionality, similar to what I did with the code.libcommsdsl
library (which allows easy navigation through the parsed schema files) and the code generation app like commsdsl2comms
which uses the library.find_package(LibCommsdsl)
in yours.commsdsl2comms
application of this project in order to make it easily accessible to other people.commsdsl
library and make it common for all applications. As the short term solution just copy-paste it to your application. It can be cleaned later.Hope it helps.
Hi Alex, thanks for the feedback. An ICD generally describes way more than just the protocol, also the electrical and mechanical aspects of an interface. But this auto generation will focus only on the protocol description. Because the description is often part of a bigger document, it should only generate the files. The user should include these into the actual document.
I'll implement it first as a standalone tool.
https://github.com/mathisloge/protocol-doc-generation
So I've worked a bit on it. But it is far away from testable. Just wanted to let you know, that there is some progress. Using https://github.com/pantor/inja to generate text from templates. In the end all structures has to be converted to an internal json structure. But, which i do like quite a lot, it is possibile to override text etc. by appying a json merge.
Hi Alex, quick question: The StringField has a encoding state which will default to the common::encoding. (https://github.com/commschamp/commsdsl/blob/ba636a97316210beabcb8e27e15a10fa198d10d9/lib/src/StringFieldImpl.cpp#L219 and FF) But I couldn't find any info about it in https://commschamp.github.io/commsdsl_spec/#appendix-string
Do I have to take the encoding into account or can I ignore it (treat it just a internal code gen thing)?
Hi Mathis, When I introduced the relevant code, the intention was to put the string encoding information (like ascii, utf-8, etc...) into the schema. The libcommsdsl parses and exposes its information in the API. However, the COMMS library and comms_champion project doesn't have any use for this information, and consequently commsdsl2comms code generator. At least for now. As the result I also decided not to document it in the spec and leave it as undocumented feature for the future. Besides, I still haven't decided for the range of valid values. Potentially it should become an enum instead of the string in the StringField API.
Please disregard it for now unless you really need to specify it as part of the schema, not just
Hi Alex, thanks for the explanation!
Then I will ignore the field for now.
Hi Alex,
I'm currently exploring the possibility to generate latex files for automatic ICD generation. there shouldn't be much missing for a ICD generation. (just the protocol aspect of a ICD.) But I think that this will be a very useful functionality.
https://github.com/mathisloge/commsdsl
I'm letting you know how it works out. Currently i need to dig a bit around the code to get a better understanding. (Don't expect me to be that fast. I'm currently writing my master thesis and working beside that)
Just by the way, really good code. I was able to find my way around quickly and generated the first latex document.