Creating out of source doc files

1 files changed, 254 insertions, 0 deletions

diff --git a/docs_oos/entity.schema.json b/docs_oos/entity.schema.json
new file mode 100644
index 0000000..73011a7
--- /dev/null
+++ b/docs_oos/entity.schema.json
@@ -0,0 +1,254 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "forstio/docs_oos/entity.schema.json",
+	"title": "forstio out of source api entity",
+	"description": "One file per entity, written by hand instead of derived from doxygen. A primary template and each of its specializations are separate files with their own id; the primary links the specializations, which the tree renders as a sublist underneath it. The generator collects every file under docs_oos/data into one map keyed by id, which is the shape the rst templates consume.",
+	"type": "object",
+	"required": ["format", "id", "kind", "name", "namespace", "header"],
+	"additionalProperties": false,
+	"properties": {
+		"format": {
+			"const": 1
+		},
+		"id": {
+			"type": "string",
+			"pattern": "^[a-z0-9_]+(-[a-z0-9_]+)*$",
+			"description": "Stable identifier. Becomes the rst file name, the label and the :ref: target, so it replaces the doxygen refid. Convention: namespace and name joined by a dash, with a slug for a specialization, e.g. saw-data_server and saw-data_server-loopback."
+		},
+		"kind": {
+			"enum": ["class", "struct", "alias", "function", "variable", "enum", "concept", "namespace"]
+		},
+		"name": {
+			"type": "string",
+			"description": "Unqualified name without namespace and without template arguments. A specialization carries the same name as its primary."
+		},
+		"namespace": {
+			"type": "string",
+			"description": "Where it lives, e.g. saw or saw::rmt. Kept apart from the name so the heading stays readable and the namespace can still be shown."
+		},
+		"module": {
+			"type": "string",
+			"description": "Module directory, e.g. remote."
+		},
+		"header": {
+			"type": "string",
+			"description": "Declaring header, relative to the repository root."
+		},
+		"brief_description": {
+			"type": "string"
+		},
+		"detailed_description": {
+			"$ref": "#/$defs/paragraphs"
+		},
+		"templates": {
+			"type": "array",
+			"description": "Template parameters. A partial specialization lists the parameters it introduces, not the ones it binds.",
+			"items": {"$ref": "#/$defs/template_parameter"}
+		},
+		"is_special": {
+			"type": "boolean",
+			"default": false,
+			"description": "True on a specialization. The index skips these; they are reachable through their primary."
+		},
+		"specializes": {
+			"type": "string",
+			"description": "Only on a specialization: id of the primary."
+		},
+		"arguments": {
+			"type": "array",
+			"description": "Only on a specialization: the arguments it binds, in order, as written.",
+			"items": {"type": "string"}
+		},
+		"specializations": {
+			"type": "array",
+			"description": "Only on a primary. Rendered as the sublist under the entity.",
+			"items": {"$ref": "#/$defs/specialization_link"}
+		},
+		"aliases": {
+			"type": "object",
+			"description": "Member type aliases keyed by id. These carry weight here, e.g. DataServers or InterfaceT.",
+			"additionalProperties": {"$ref": "#/$defs/alias"}
+		},
+		"attributes": {
+			"type": "object",
+			"description": "Data members keyed by id.",
+			"additionalProperties": {"$ref": "#/$defs/attribute"}
+		},
+		"functions": {
+			"type": "object",
+			"description": "Member functions keyed by id. Overloads get distinct ids.",
+			"additionalProperties": {"$ref": "#/$defs/function"}
+		},
+		"examples": {
+			"type": "array",
+			"description": "Usage examples for the entity as a whole.",
+			"items": {"$ref": "#/$defs/example"}
+		},
+		"notes": {
+			"type": "array",
+			"description": "Remarks which don't belong to a single member.",
+			"items": {"type": "string"}
+		}
+	},
+	"$defs": {
+		"example": {
+			"type": "object",
+			"required": ["code"],
+			"additionalProperties": false,
+			"properties": {
+				"title": {"type": "string"},
+				"language": {
+					"type": "string",
+					"default": "cpp",
+					"description": "Rendered as the code block language."
+				},
+				"description": {"$ref": "#/$defs/paragraphs"},
+				"code": {
+					"type": "string",
+					"description": "Source as a single string with newlines. Error handling may be left out for readability, but then the description has to say so."
+				}
+			}
+		},
+		"paragraphs": {
+			"type": "array",
+			"description": "A list of paragraphs. Each paragraph is a list of fragments: plain strings, or a reference object which renders as a link to another entity.",
+			"items": {
+				"type": "array",
+				"items": {
+					"oneOf": [
+						{"type": "string"},
+						{"$ref": "#/$defs/type_ref"}
+					]
+				}
+			}
+		},
+		"type_ref": {
+			"type": "object",
+			"required": ["name", "id"],
+			"additionalProperties": false,
+			"properties": {
+				"name": {"type": "string", "description": "Text to display."},
+				"id": {"type": "string", "description": "id of the entity being linked."}
+			}
+		},
+		"type_tuple": {
+			"type": "array",
+			"description": "A type as a sequence of fragments, so the parts which are entities link and the rest stays text.",
+			"items": {
+				"oneOf": [
+					{"type": "string"},
+					{"$ref": "#/$defs/type_ref"}
+				]
+			}
+		},
+		"template_parameter": {
+			"type": "object",
+			"required": ["name", "kind"],
+			"additionalProperties": false,
+			"properties": {
+				"name": {"type": "string"},
+				"kind": {
+					"enum": ["type", "non_type", "template"],
+					"description": "type for class/typename, non_type for a value parameter such as uint64_t N or string_literal Lit."
+				},
+				"type": {
+					"type": "string",
+					"description": "Required for non_type, e.g. uint64_t or string_literal."
+				},
+				"pack": {"type": "boolean", "default": false},
+				"default": {"type": "string", "description": "Default argument as written."},
+				"brief_description": {"type": "string"}
+			}
+		},
+		"specialization_link": {
+			"type": "object",
+			"required": ["name", "id"],
+			"additionalProperties": false,
+			"properties": {
+				"name": {
+					"type": "string",
+					"description": "Specialized name as it should read in the sublist, e.g. data_server< Schema, Encoding, rmt::Loopback >."
+				},
+				"id": {"type": "string"},
+				"brief_description": {
+					"type": "string",
+					"description": "One line, so the sublist says what the specialization is for without opening it."
+				}
+			}
+		},
+		"alias": {
+			"type": "object",
+			"required": ["id", "name", "type"],
+			"additionalProperties": false,
+			"properties": {
+				"id": {"type": "string"},
+				"name": {"type": "string"},
+				"type": {"$ref": "#/$defs/type_tuple"},
+				"visibility": {"enum": ["public", "protected", "private"], "default": "public"},
+				"brief_description": {"type": "string"},
+				"detailed_description": {"$ref": "#/$defs/paragraphs"}
+			}
+		},
+		"attribute": {
+			"type": "object",
+			"required": ["id", "name", "type"],
+			"additionalProperties": false,
+			"properties": {
+				"id": {"type": "string"},
+				"name": {"type": "string"},
+				"type": {"$ref": "#/$defs/type_tuple"},
+				"visibility": {"enum": ["public", "protected", "private"], "default": "private"},
+				"static": {"type": "boolean", "default": false},
+				"const": {"type": "boolean", "default": false},
+				"constexpr": {"type": "boolean", "default": false},
+				"initializer": {"type": "string", "default": ""},
+				"brief_description": {"type": "string"},
+				"detailed_description": {"$ref": "#/$defs/paragraphs"}
+			}
+		},
+		"function": {
+			"type": "object",
+			"required": ["id", "name", "type"],
+			"additionalProperties": false,
+			"properties": {
+				"id": {"type": "string"},
+				"name": {"type": "string"},
+				"type": {
+					"$ref": "#/$defs/type_tuple",
+					"description": "Return type. Empty for constructors and destructors."
+				},
+				"templates": {
+					"type": "array",
+					"description": "Template parameters of the function itself, e.g. the string_literal naming an interface member.",
+					"items": {"$ref": "#/$defs/template_parameter"}
+				},
+				"parameters": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"required": ["name", "type"],
+						"additionalProperties": false,
+						"properties": {
+							"name": {"type": "string"},
+							"type": {"$ref": "#/$defs/type_tuple"},
+							"default": {"type": "string"},
+							"brief_description": {"type": "string"}
+						}
+					}
+				},
+				"visibility": {"enum": ["public", "protected", "private"], "default": "public"},
+				"static": {"type": "boolean", "default": false},
+				"const": {"type": "boolean", "default": false},
+				"virtual": {"type": "boolean", "default": false},
+				"override": {"type": "boolean", "default": false},
+				"brief_description": {"type": "string"},
+				"detailed_description": {"$ref": "#/$defs/paragraphs"},
+				"examples": {
+					"type": "array",
+					"description": "Usage examples for this member.",
+					"items": {"$ref": "#/$defs/example"}
+				}
+			}
+		}
+	}
+}