docs: Enable since/version handling for XML, CLI and ARI documentation

* Added the "since" element to the XML configObject and configOption elements
  in appdocsxml.dtd.

* Added the "Since" section to the following CLI output:
  ```
  config show help <module> <object>
  config show help <module> <object> <option>
  core show application <app>
  core show function <func>
  manager show command <command>
  manager show event <event>
  agi show commands topic <topic>
  ```

* Refactored the commands above to output their sections in the same order:
  Synopsis, Since, Description, Syntax, Arguments, SeeAlso

* Refactored the commands above so they all use the same pattern for writing
  the output to the CLI.

* Fixed several memory leaks caused by failure to free temporary output
  buffers.

* Added a "since" array to the mustache template for the top-level resources
  (Channel, Endpoint, etc.) and to the paths/methods underneath them. These
  will be added to the generated markdown if present.
  Example:
  ```
    "resourcePath": "/api-docs/channels.{format}",
    "requiresModules": [
        "res_stasis_answer",
        "res_stasis_playback",
        "res_stasis_recording",
        "res_stasis_snoop"
    ],
    "since": [
        "18.0.0",
        "21.0.0"
    ],
    "apis": [
        {
            "path": "/channels",
            "description": "Active channels",
            "operations": [
                {
                    "httpMethod": "GET",
                    "since": [
                        "18.6.0",
                        "21.8.0"
                    ],
                    "summary": "List all active channels in Asterisk.",
                    "nickname": "list",
                    "responseClass": "List[Channel]"
                },

  ```

NOTE:  No versioning information is actually added in this commit.
Those will be added separately and instructions for adding and maintaining
them will be published on the documentation site at a later date.

(cherry picked from commit d5e7988df4)
This commit is contained in:
George Joseph
2025-01-09 15:17:14 -07:00
committed by Asterisk Development Team
parent 82c1fb71e6
commit a21971cfeb
13 changed files with 493 additions and 272 deletions

View File

@@ -1,11 +1,14 @@
{{#api_declaration}}
# {{name_title}}
{{#since}}
## Since: {{since}}
{{/since}}
| Method | Path (Parameters are case-sensitive) | Return Model | Summary |
|:------ |:------------------------------------ |:------------ |:------- |
| Method | Path (Parameters are case-sensitive) | Return Model | Summary | Since |
|:------ |:------------------------------------ |:------------ |:------- |:----- |
{{#apis}}
{{#operations}}
| {{http_method}} | [{{wiki_path}}](#{{nickname_lc}}) | {{#response_class}}{{#is_primitive}}{{name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}]({{wiki_prefix}}Asterisk_REST_Data_Models#{{lc_singular_name}}){{/is_primitive}}{{/response_class}} | {{{summary}}} |
| {{http_method}} | [{{wiki_path}}](#{{nickname_lc}}) | {{#response_class}}{{#is_primitive}}{{name}}{{/is_primitive}}{{^is_primitive}}[{{wiki_name}}]({{wiki_prefix}}Asterisk_REST_Data_Models#{{lc_singular_name}}){{/is_primitive}}{{/response_class}} | {{{summary}}} | {{since}} |
{{/operations}}
{{/apis}}
{{#apis}}
@@ -14,6 +17,9 @@
---
[//]: # (anchor:{{nickname_lc}})
## {{nickname}}
{{#since}}
### Since: {{since}}
{{/since}}
### {{http_method}} {{wiki_path}}
{{{wiki_summary}}}{{#wiki_notes}} {{{wiki_notes}}}{{/wiki_notes}}
{{#has_path_parameters}}

View File

@@ -373,6 +373,7 @@ class Operation(Stringify):
self.summary = None
self.notes = None
self.error_responses = []
self.since = []
def load(self, op_json, processor, context):
context = context.next_stack(op_json, 'nickname')
@@ -383,6 +384,8 @@ class Operation(Stringify):
response_class = op_json.get('responseClass')
self.response_class = response_class and SwaggerType().load(
response_class, processor, context)
since = op_json.get('since') or []
self.since = ", ".join(since)
# Specifying WebSocket URL's is our own extension
self.is_websocket = op_json.get('upgrade') == 'websocket'
@@ -611,6 +614,7 @@ class ApiDeclaration(Stringify):
self.api_version = None
self.base_path = None
self.resource_path = None
self.since = []
self.apis = []
self.models = []
@@ -658,6 +662,8 @@ class ApiDeclaration(Stringify):
self.base_path = api_decl_json.get('basePath')
self.resource_path = api_decl_json.get('resourcePath')
self.requires_modules = api_decl_json.get('requiresModules') or []
since = api_decl_json.get('since') or []
self.since = ", ".join(since)
api_json = api_decl_json.get('apis') or []
self.apis = [
Api().load(j, processor, context) for j in api_json]