diff --git a/jsonschema.go b/jsonschema.go index 921af67..5955b8e 100644 --- a/jsonschema.go +++ b/jsonschema.go @@ -24,6 +24,7 @@ func makeJSONSchema(t any, yaml bool) string { if yaml { selectedReflector = yamlReflector } + selectedReflector.AddGoComments("github.com/ortfo/db", "./") schema := selectedReflector.Reflect(t) setSchemaId(schema) out, err := json.MarshalIndent(schema, "", " ") diff --git a/packages/python/ortfodb/configuration.py b/packages/python/ortfodb/configuration.py index 56b785d..9791655 100644 --- a/packages/python/ortfodb/configuration.py +++ b/packages/python/ortfodb/configuration.py @@ -181,13 +181,19 @@ def to_dict(self) -> dict: class Configuration: + """Configuration represents what the ortfodb.yaml configuration file describes.""" + build_metadata_file: str exporters: Optional[Dict[str, Dict[str, Any]]] + """Exporter-specific configuration. Maps exporter names to their configuration.""" + extract_colors: ExtractColors make_gifs: MakeGifs make_thumbnails: MakeThumbnails media: Media projects_at: str + """Path to the directory containing all projects. Must be absolute.""" + scattered_mode_folder: str tags: Tags technologies: Technologies diff --git a/packages/python/ortfodb/database.py b/packages/python/ortfodb/database.py index 9605b7a..178b6fc 100644 --- a/packages/python/ortfodb/database.py +++ b/packages/python/ortfodb/database.py @@ -45,11 +45,22 @@ def from_dict(f: Callable[[Any], T], x: Any) -> Dict[str, T]: class Attributes: + """MediaAttributes stores which HTML attributes should be added to the media.""" + autoplay: bool + """Controlled with attribute character > (adds)""" + controls: bool + """Controlled with attribute character = (removes)""" + loop: bool + """Controlled with attribute character ~ (adds)""" + muted: bool + """Controlled with attribute character > (adds)""" + playsinline: bool + """Controlled with attribute character = (adds)""" def __init__(self, autoplay: bool, controls: bool, loop: bool, muted: bool, playsinline: bool) -> None: self.autoplay = autoplay @@ -79,6 +90,8 @@ def to_dict(self) -> dict: class Colors: + """ColorPalette reprensents the object in a Work's metadata.colors.""" + primary: str secondary: str tertiary: str @@ -105,9 +118,16 @@ def to_dict(self) -> dict: class Dimensions: + """ImageDimensions represents metadata about a media as it's extracted from its file.""" + aspect_ratio: float + """width / height""" + height: int + """Height in pixels""" + width: int + """Width in pixels""" def __init__(self, aspect_ratio: float, height: int, width: int) -> None: self.aspect_ratio = aspect_ratio @@ -149,21 +169,29 @@ def to_dict(self) -> dict: class BlockElement: alt: str analyzed: bool + """whether the media has been analyzed""" + anchor: str attributes: Attributes caption: str colors: Colors content: str + """html""" + content_type: str dimensions: Dimensions dist_source: str duration: float + """in seconds""" + has_sound: bool id: str index: int online: bool relative_source: str size: int + """in bytes""" + text: str thumbnails: Thumbnails thumbnails_built_at: str @@ -284,6 +312,7 @@ def to_dict(self) -> dict: class DatabaseMetadataClass: partial: bool + """Partial is true if the database was not fully built.""" def __init__(self, partial: bool) -> None: self.partial = partial @@ -367,6 +396,8 @@ def to_dict(self) -> dict: class DatabaseValue: + """AnalyzedWork represents a complete work, with analyzed mediae.""" + built_at: str content: Dict[str, ContentValue] description_hash: str diff --git a/packages/python/ortfodb/technologies.py b/packages/python/ortfodb/technologies.py index 4d63f7a..5f81769 100644 --- a/packages/python/ortfodb/technologies.py +++ b/packages/python/ortfodb/technologies.py @@ -22,9 +22,16 @@ def to_class(c: Type[T], x: Any) -> dict: class Technology: aliases: List[str] autodetect: List[str] + """Autodetect contains an expression of the form 'CONTENT in PATH' where CONTENT is a + free-form unquoted string and PATH is a filepath relative to the work folder. + If CONTENT is found in PATH, we consider that technology to be used in the work. + """ by: str description: str files: List[str] + """Files contains a list of gitignore-style patterns. If the work contains any of the + patterns specified, we consider that technology to be used in the work. + """ learn_more_at: str name: str slug: str diff --git a/packages/rust/src/configuration.rs b/packages/rust/src/configuration.rs index ad55d94..2876c97 100644 --- a/packages/rust/src/configuration.rs +++ b/packages/rust/src/configuration.rs @@ -14,11 +14,13 @@ use serde::{Serialize, Deserialize}; use std::collections::HashMap; +/// Configuration represents what the ortfodb.yaml configuration file describes. #[derive(Serialize, Deserialize)] pub struct Configuration { #[serde(rename = "build metadata file")] pub build_metadata_file: String, + /// Exporter-specific configuration. Maps exporter names to their configuration. pub exporters: Option>>>, #[serde(rename = "extract colors")] @@ -32,6 +34,7 @@ pub struct Configuration { pub media: Media, + /// Path to the directory containing all projects. Must be absolute. #[serde(rename = "projects at")] pub projects_at: String, diff --git a/packages/rust/src/database.rs b/packages/rust/src/database.rs index 32ce226..805cf79 100644 --- a/packages/rust/src/database.rs +++ b/packages/rust/src/database.rs @@ -16,6 +16,7 @@ use std::collections::HashMap; pub type Database = HashMap; +/// AnalyzedWork represents a complete work, with analyzed mediae. #[derive(Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct DatabaseValue { @@ -49,6 +50,7 @@ pub struct ContentValue { pub struct BlockElement { pub alt: String, + /// whether the media has been analyzed pub analyzed: bool, pub anchor: String, @@ -59,6 +61,7 @@ pub struct BlockElement { pub colors: Colors, + /// html pub content: String, pub content_type: String, @@ -67,6 +70,7 @@ pub struct BlockElement { pub dist_source: String, + /// in seconds pub duration: f64, pub has_sound: bool, @@ -79,6 +83,7 @@ pub struct BlockElement { pub relative_source: String, + /// in bytes pub size: i64, pub text: String, @@ -95,20 +100,27 @@ pub struct BlockElement { pub url: String, } +/// MediaAttributes stores which HTML attributes should be added to the media. #[derive(Serialize, Deserialize)] pub struct Attributes { + /// Controlled with attribute character > (adds) pub autoplay: bool, + /// Controlled with attribute character = (removes) pub controls: bool, + /// Controlled with attribute character ~ (adds) #[serde(rename = "loop")] pub attributes_loop: bool, + /// Controlled with attribute character > (adds) pub muted: bool, + /// Controlled with attribute character = (adds) pub playsinline: bool, } +/// ColorPalette reprensents the object in a Work's metadata.colors. #[derive(Serialize, Deserialize)] pub struct Colors { pub primary: String, @@ -118,13 +130,17 @@ pub struct Colors { pub tertiary: String, } +/// ImageDimensions represents metadata about a media as it's extracted from its file. #[derive(Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct Dimensions { + /// width / height pub aspect_ratio: f64, + /// Height in pixels pub height: i64, + /// Width in pixels pub width: i64, } @@ -165,5 +181,6 @@ pub struct Metadata { #[derive(Serialize, Deserialize)] #[serde(rename_all = "PascalCase")] pub struct DatabaseMetadataClass { + /// Partial is true if the database was not fully built. pub partial: bool, } diff --git a/packages/rust/src/technologies.rs b/packages/rust/src/technologies.rs index ca83c1e..ee9f1af 100644 --- a/packages/rust/src/technologies.rs +++ b/packages/rust/src/technologies.rs @@ -19,12 +19,17 @@ pub type Technologies = Vec; pub struct Technology { pub aliases: Vec, + /// Autodetect contains an expression of the form 'CONTENT in PATH' where CONTENT is a + /// free-form unquoted string and PATH is a filepath relative to the work folder. + /// If CONTENT is found in PATH, we consider that technology to be used in the work. pub autodetect: Vec, pub by: String, pub description: String, + /// Files contains a list of gitignore-style patterns. If the work contains any of the + /// patterns specified, we consider that technology to be used in the work. pub files: Vec, #[serde(rename = "learn more at")] diff --git a/packages/typescript/src/configuration.ts b/packages/typescript/src/configuration.ts index fa3eb65..f4da7cd 100644 --- a/packages/typescript/src/configuration.ts +++ b/packages/typescript/src/configuration.ts @@ -7,13 +7,22 @@ // These functions will throw an error if the JSON doesn't // match the expected interface, even if the JSON is valid. +/** + * Configuration represents what the ortfodb.yaml configuration file describes. + */ export interface Configuration { - "build metadata file": string; - exporters?: { [key: string]: { [key: string]: any } }; - "extract colors": ExtractColors; - "make gifs": MakeGifs; - "make thumbnails": MakeThumbnails; - media: Media; + "build metadata file": string; + /** + * Exporter-specific configuration. Maps exporter names to their configuration. + */ + exporters?: { [key: string]: { [key: string]: any } }; + "extract colors": ExtractColors; + "make gifs": MakeGifs; + "make thumbnails": MakeThumbnails; + media: Media; + /** + * Path to the directory containing all projects. Must be absolute. + */ "projects at": string; "scattered mode folder": string; tags: Tags; diff --git a/packages/typescript/src/database.ts b/packages/typescript/src/database.ts index 6833f39..75b49f5 100644 --- a/packages/typescript/src/database.ts +++ b/packages/typescript/src/database.ts @@ -7,6 +7,9 @@ // These functions will throw an error if the JSON doesn't // match the expected interface, even if the JSON is valid. +/** + * AnalyzedWork represents a complete work, with analyzed mediae. + */ export interface Database { builtAt: string; content: { [key: string]: ContentValue }; @@ -24,22 +27,34 @@ export interface ContentValue { } export interface BlockElement { - alt: string; - analyzed: boolean; - anchor: string; - attributes: Attributes; - caption: string; - colors: Colors; - content: string; - contentType: string; - dimensions: Dimensions; - distSource: string; - duration: number; - hasSound: boolean; - id: string; - index: number; - online: boolean; - relativeSource: string; + alt: string; + /** + * whether the media has been analyzed + */ + analyzed: boolean; + anchor: string; + attributes: Attributes; + caption: string; + colors: Colors; + /** + * html + */ + content: string; + contentType: string; + dimensions: Dimensions; + distSource: string; + /** + * in seconds + */ + duration: number; + hasSound: boolean; + id: string; + index: number; + online: boolean; + relativeSource: string; + /** + * in bytes + */ size: number; text: string; thumbnails: Thumbnails; @@ -49,24 +64,57 @@ export interface BlockElement { url: string; } +/** + * MediaAttributes stores which HTML attributes should be added to the media. + */ export interface Attributes { - autoplay: boolean; - controls: boolean; - loop: boolean; - muted: boolean; + /** + * Controlled with attribute character > (adds) + */ + autoplay: boolean; + /** + * Controlled with attribute character = (removes) + */ + controls: boolean; + /** + * Controlled with attribute character ~ (adds) + */ + loop: boolean; + /** + * Controlled with attribute character > (adds) + */ + muted: boolean; + /** + * Controlled with attribute character = (adds) + */ playsinline: boolean; } +/** + * ColorPalette reprensents the object in a Work's metadata.colors. + */ export interface Colors { primary: string; secondary: string; tertiary: string; } +/** + * ImageDimensions represents metadata about a media as it's extracted from its file. + */ export interface Dimensions { + /** + * width / height + */ aspectRatio: number; - height: number; - width: number; + /** + * Height in pixels + */ + height: number; + /** + * Width in pixels + */ + width: number; } export interface Thumbnails { @@ -89,6 +137,9 @@ export interface Metadata { } export interface DatabaseMetadataClass { + /** + * Partial is true if the database was not fully built. + */ Partial: boolean; } diff --git a/packages/typescript/src/technologies.ts b/packages/typescript/src/technologies.ts index 3679829..301966e 100644 --- a/packages/typescript/src/technologies.ts +++ b/packages/typescript/src/technologies.ts @@ -8,10 +8,19 @@ // match the expected interface, even if the JSON is valid. export interface Technologies { - aliases: string[]; - autodetect: string[]; - by: string; - description: string; + aliases: string[]; + /** + * Autodetect contains an expression of the form 'CONTENT in PATH' where CONTENT is a + * free-form unquoted string and PATH is a filepath relative to the work folder. + * If CONTENT is found in PATH, we consider that technology to be used in the work. + */ + autodetect: string[]; + by: string; + description: string; + /** + * Files contains a list of gitignore-style patterns. If the work contains any of the + * patterns specified, we consider that technology to be used in the work. + */ files: string[]; "learn more at": string; name: string; diff --git a/schemas/configuration.schema.json b/schemas/configuration.schema.json index 5b7b6c5..819c5fc 100644 --- a/schemas/configuration.schema.json +++ b/schemas/configuration.schema.json @@ -57,13 +57,15 @@ ] }, "projects at": { - "type": "string" + "type": "string", + "description": "Path to the directory containing all projects. Must be absolute." }, "exporters": { "additionalProperties": { "type": "object" }, - "type": "object" + "type": "object", + "description": "Exporter-specific configuration. Maps exporter names to their configuration." } }, "additionalProperties": false, @@ -78,7 +80,8 @@ "tags", "technologies", "projects at" - ] + ], + "description": "Configuration represents what the ortfodb.yaml configuration file describes." }, "ExtractColorsConfiguration": { "properties": { diff --git a/schemas/database.schema.json b/schemas/database.schema.json index 2c01af4..645af95 100644 --- a/schemas/database.schema.json +++ b/schemas/database.schema.json @@ -33,7 +33,8 @@ "metadata", "content", "Partial" - ] + ], + "description": "AnalyzedWork represents a complete work, with analyzed mediae." }, "ColorPalette": { "properties": { @@ -53,7 +54,8 @@ "primary", "secondary", "tertiary" - ] + ], + "description": "ColorPalette reprensents the object in a Work's metadata.colors." }, "ContentBlock": { "properties": { @@ -85,7 +87,8 @@ "type": "string" }, "size": { - "type": "integer" + "type": "integer", + "description": "in bytes" }, "dimensions": { "$ref": "#/$defs/ImageDimensions" @@ -94,7 +97,8 @@ "type": "boolean" }, "duration": { - "type": "number" + "type": "number", + "description": "in seconds" }, "hasSound": { "type": "boolean" @@ -112,10 +116,12 @@ "$ref": "#/$defs/MediaAttributes" }, "analyzed": { - "type": "boolean" + "type": "boolean", + "description": "whether the media has been analyzed" }, "content": { - "type": "string" + "type": "string", + "description": "html" }, "text": { "type": "string" @@ -164,7 +170,8 @@ "DatabaseMeta": { "properties": { "Partial": { - "type": "boolean" + "type": "boolean", + "description": "Partial is true if the database was not fully built." } }, "additionalProperties": false, @@ -177,18 +184,22 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Footnotes represents the footnote declarations in a description.md file." }, "ImageDimensions": { "properties": { "width": { - "type": "integer" + "type": "integer", + "description": "Width in pixels" }, "height": { - "type": "integer" + "type": "integer", + "description": "Height in pixels" }, "aspectRatio": { - "type": "number" + "type": "number", + "description": "width / height" } }, "additionalProperties": false, @@ -197,7 +208,8 @@ "width", "height", "aspectRatio" - ] + ], + "description": "ImageDimensions represents metadata about a media as it's extracted from its file." }, "Layout": { "items": { @@ -206,7 +218,8 @@ }, "type": "array" }, - "type": "array" + "type": "array", + "description": "Layout is a 2D array of content block IDs" }, "LocalizableContent": { "additionalProperties": { @@ -244,19 +257,24 @@ "MediaAttributes": { "properties": { "loop": { - "type": "boolean" + "type": "boolean", + "description": "Controlled with attribute character ~ (adds)" }, "autoplay": { - "type": "boolean" + "type": "boolean", + "description": "Controlled with attribute character \u003e (adds)" }, "muted": { - "type": "boolean" + "type": "boolean", + "description": "Controlled with attribute character \u003e (adds)" }, "playsinline": { - "type": "boolean" + "type": "boolean", + "description": "Controlled with attribute character = (adds)" }, "controls": { - "type": "boolean" + "type": "boolean", + "description": "Controlled with attribute character = (removes)" } }, "additionalProperties": false, @@ -267,7 +285,8 @@ "muted", "playsinline", "controls" - ] + ], + "description": "MediaAttributes stores which HTML attributes should be added to the media." }, "ThumbnailsMap": { "patternProperties": { diff --git a/schemas/technologies.schema.json b/schemas/technologies.schema.json index b4d2fe8..ba6195a 100644 --- a/schemas/technologies.schema.json +++ b/schemas/technologies.schema.json @@ -30,13 +30,15 @@ "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Files contains a list of gitignore-style patterns. If the work contains any of the patterns specified, we consider that technology to be used in the work." }, "autodetect": { "items": { "type": "string" }, - "type": "array" + "type": "array", + "description": "Autodetect contains an expression of the form 'CONTENT in PATH' where CONTENT is a free-form unquoted string and PATH is a filepath relative to the work folder.\nIf CONTENT is found in PATH, we consider that technology to be used in the work." } }, "additionalProperties": false,