Improve the generated markdown about ctim HOT 11 CLOSED

• Add Usage Notes to leaf nodes

from ctim.

• There should be an index page that points to the various generated documents
• Need to delete old schema docs in CTIM and CTIA (threatgrid/ctia#423)

from ctim.

I think you should just make :description be markdown, that way if I want a link, I can write it out as markdown, and I get all the other markdown behavior.

from ctim.

I believe we hit the issue for :description used in swagger (which I don't think support markdown) and adding another field, :long-description that would be able to handle markdown and be used for more in depth documentation.

from ctim.

Since markdown is just text, why is the lack of support for it in swagger an isue?

from ctim.

In swagger-ui the text describing a field is intended be "short".

For example this is what swagger-ui display when an user click on Model description:

Log {
tags (Array[string], optional): An optional list of strings ,
_event_type (string, optional): The type of event for example syslog, cisco_syslog, wsa_log ,
_format (string, optional): The optional logstash codec, default is plain another common is json ,
@timestamp (string): Event occured at ,
_collector (string): The name of the collector this event came through ,
_raw (string): The raw, original event text ,
@version (string): Event schema version ,
_source (string): The source, a file path, socket or url path or other identifier specific to _input ,
_encoding (string, optional): The character set of the event, default UTF-8 ,
_input (string): The name of the input module this event came via
}

If we write a long description, it will certainly be hard to read in swagger-ui.

But we also sometime need to be able to add a long, in-depth description.
Typically when we generate a documentation in another format than an interactive app.
Of course as for now, we use a middle man to generate "descriptions" in schemas we could apply a function that depending on the output (swagger or markdown documentation) could cut the description to some reasonable length.

from ctim.

Well, the convention we have in other places is :short_description and :description, with :short_description being a pure string. Why not use that?

from ctim.

yes, that feels right.

from ctim.

We could truncate the description when we generate the schema that swagger sees (or modify it in some other way).

from ctim.

Currently I am assuming that descriptions (and references) are markdown.

from ctim.

@Steve yah, I believe the convention we settled on in other places was the use :short_description if present, otherwise break on first sentence, or paragraph of the full description.

from ctim.