From 7b337233800cf55604dbaeb911a174b1d71e0de6 Mon Sep 17 00:00:00 2001 From: Sina Atalay Date: Sat, 17 Feb 2024 19:45:10 +0100 Subject: [PATCH] document theme options --- rendercv/themes/__init__.py | 67 ++++++++++++----- rendercv/themes/classic/__init__.py | 5 +- rendercv/themes/moderncv/__init__.py | 6 +- rendercv/themes/sb2nov/__init__.py | 2 +- schema.json | 106 ++++++++++++++------------- 5 files changed, 111 insertions(+), 75 deletions(-) diff --git a/rendercv/themes/__init__.py b/rendercv/themes/__init__.py index c5eb10f..c6b075d 100644 --- a/rendercv/themes/__init__.py +++ b/rendercv/themes/__init__.py @@ -1,10 +1,18 @@ -""" """ +"""This module containts some general-purpose data models for the themes. The themes +are encouraged to inherit from these data models and add their own options, to avoid +code duplication. +""" from typing import Literal, Annotated import pydantic import pydantic_extra_types.color as pydantic_color +# Create a custom type called LaTeXDimension that accepts only strings in a specified +# format. +# This type is used to validate the dimension fields in the design data. +# See https://docs.pydantic.dev/2.5/concepts/types/#custom-types for more information +# about custom types. LaTeXDimension = Annotated[ str, pydantic.Field( @@ -14,42 +22,54 @@ LaTeXDimension = Annotated[ class PageMargins(pydantic.BaseModel): + """This class is a data model for the page margins.""" + top: LaTeXDimension = pydantic.Field( default="2 cm", title="Top Margin", - description="The top margin of the page with units.", + description="The top margin of the page with units. The default value is 2 cm.", ) bottom: LaTeXDimension = pydantic.Field( default="2 cm", title="Bottom Margin", - description="The bottom margin of the page with units.", + description=( + "The bottom margin of the page with units. The default value is 2 cm." + ), ) left: LaTeXDimension = pydantic.Field( - default="1.24 cm", + default="2 cm", title="Left Margin", - description="The left margin of the page with units.", + description=( + "The left margin of the page with units. The default value is 2 cm." + ), ) right: LaTeXDimension = pydantic.Field( - default="1.24 cm", + default="2 cm", title="Right Margin", - description="The right margin of the page with units.", + description=( + "The right margin of the page with units. The default value is 2 cm." + ), ) class SectionTitleMargins(pydantic.BaseModel): + """This class is a data model for the section title margins.""" + top: LaTeXDimension = pydantic.Field( - default="0.2 cm", + default="0.3 cm", title="Top Margin", - description="The top margin of section titles. The default value is 0.2 cm.", + description="The top margin of section titles. The default value is 0.3 cm.", ) bottom: LaTeXDimension = pydantic.Field( default="0.2 cm", title="Bottom Margin", - description="The bottom margin of section titles. The default value is 0.2 cm.", + description="The bottom margin of section titles. The default value is 0.3 cm.", ) class EntryAreaMargins(pydantic.BaseModel): + """This class is a data model for the entry area margins.""" + left_and_right: LaTeXDimension = pydantic.Field( default="0.2 cm", title="Left Margin", @@ -57,10 +77,10 @@ class EntryAreaMargins(pydantic.BaseModel): ) vertical_between: LaTeXDimension = pydantic.Field( - default="0.12 cm", + default="0.2 cm", title="Vertical Margin Between Entry Areas", description=( - "The vertical margin between entry areas. The default value is 0.12 cm." + "The vertical margin between entry areas. The default value is 0.2 cm." ), ) @@ -74,6 +94,8 @@ class EntryAreaMargins(pydantic.BaseModel): class HighlightsAreaMargins(pydantic.BaseModel): + """This class is a data model for the highlights area margins.""" + top: LaTeXDimension = pydantic.Field( default="0.10 cm", title="Top Margin", @@ -94,20 +116,22 @@ class HighlightsAreaMargins(pydantic.BaseModel): class HeaderMargins(pydantic.BaseModel): + """This class is a data model for the header margins.""" + vertical_between_name_and_connections: LaTeXDimension = pydantic.Field( - default="0.2 cm", + default="0.3 cm", title="Vertical Margin Between the Name and Connections", description=( "The vertical margin between the name of the person and the connections." - " The default value is 0.2 cm." + " The default value is 0.3 cm." ), ) bottom: LaTeXDimension = pydantic.Field( - default="0.2 cm", + default="0.3 cm", title="Bottom Margin", description=( "The bottom margin of the header, i.e., the vertical margin between the" - " connections and the first section title. The default value is 0.2 cm." + " connections and the first section title. The default value is 0.3 cm." ), ) horizontal_between_connections: LaTeXDimension = pydantic.Field( @@ -121,6 +145,8 @@ class HeaderMargins(pydantic.BaseModel): class Margins(pydantic.BaseModel): + """This class is a data model for the margins.""" + page: PageMargins = pydantic.Field( default=PageMargins(), title="Page Margins", @@ -149,7 +175,10 @@ class Margins(pydantic.BaseModel): class ThemeOptions(pydantic.BaseModel): - """ """ + """This class is a generic data model for the theme options. The themes are + encouraged to inherit from this data model and add their own options, to avoid code + duplication. + """ model_config = pydantic.ConfigDict(extra="forbid") @@ -187,13 +216,13 @@ class ThemeOptions(pydantic.BaseModel): ), ) page_numbering_style: str = pydantic.Field( - default="NAME -- Page PAGE_NUMBER of TOTAL_PAGES", + default="NAME - Page PAGE_NUMBER of TOTAL_PAGES", title="Page Numbering Style", description=( "The style of the page numbering. The following placeholders can be used:" "\n- NAME: The name of the person\n- PAGE_NUMBER: The current page number" "\n- TOTAL_PAGES: The total number of pages\nThe default value is" - " NAME -- Page PAGE_NUMBER of TOTAL_PAGES." + " NAME - Page PAGE_NUMBER of TOTAL_PAGES." ), ) show_last_updated_date: bool = pydantic.Field( diff --git a/rendercv/themes/classic/__init__.py b/rendercv/themes/classic/__init__.py index ac582c3..77fa100 100644 --- a/rendercv/themes/classic/__init__.py +++ b/rendercv/themes/classic/__init__.py @@ -6,7 +6,7 @@ from .. import ThemeOptions class ClassicThemeOptions(ThemeOptions): - """ """ + """This class is the data model of the theme options for the classic theme.""" theme: Literal["classic"] show_timespan_in: list[str] = pydantic.Field( @@ -15,6 +15,7 @@ class ClassicThemeOptions(ThemeOptions): description=( "The time span will be shown in the date and location column in these" " sections. The input should be a list of section titles as strings" - " (case-sensitive)." + " (case-sensitive). The default value is an empty list, which means the" + " time span will not be shown in any section." ), ) diff --git a/rendercv/themes/moderncv/__init__.py b/rendercv/themes/moderncv/__init__.py index a7a332c..fda5697 100644 --- a/rendercv/themes/moderncv/__init__.py +++ b/rendercv/themes/moderncv/__init__.py @@ -6,7 +6,7 @@ from .. import LaTeXDimension class ModerncvThemeOptions(pydantic.BaseModel): - """ """ + """This class is the data model of the theme options for the moderncv theme.""" model_config = pydantic.ConfigDict(extra="forbid") @@ -18,9 +18,9 @@ class ModerncvThemeOptions(pydantic.BaseModel): examples=["10pt", "11pt", "12pt"], ) page_size: Literal["a4paper", "letterpaper"] = pydantic.Field( - default="a4paper", + default="letterpaper", title="Page Size", - description='The page size of the CV. The default value is "a4paper".', + description='The page size of the CV. The default value is "letterpaper".', examples=["a4paper", "letterpaper"], ) color: ( diff --git a/rendercv/themes/sb2nov/__init__.py b/rendercv/themes/sb2nov/__init__.py index f868735..ae2f77d 100644 --- a/rendercv/themes/sb2nov/__init__.py +++ b/rendercv/themes/sb2nov/__init__.py @@ -6,7 +6,7 @@ from .. import ThemeOptions, LaTeXDimension class Sb2novThemeOptions(ThemeOptions): - """ """ + """This class is the data model of the theme options for the sb2nov theme.""" theme: Literal["sb2nov"] diff --git a/schema.json b/schema.json index ccd90d9..2492f1a 100644 --- a/schema.json +++ b/schema.json @@ -2,7 +2,7 @@ "$defs": { "ClassicThemeOptions": { "additionalProperties": false, - "description": "", + "description": "This class is the data model of the theme options for the classic theme.", "properties": { "font_size": { "default": "10pt", @@ -45,8 +45,8 @@ "type": "boolean" }, "page_numbering_style": { - "default": "NAME -- Page PAGE_NUMBER of TOTAL_PAGES", - "description": "The style of the page numbering. The following placeholders can be used:\n- NAME: The name of the person\n- PAGE_NUMBER: The current page number\n- TOTAL_PAGES: The total number of pages\nThe default value is NAME -- Page PAGE_NUMBER of TOTAL_PAGES.", + "default": "NAME - Page PAGE_NUMBER of TOTAL_PAGES", + "description": "The style of the page numbering. The following placeholders can be used:\n- NAME: The name of the person\n- PAGE_NUMBER: The current page number\n- TOTAL_PAGES: The total number of pages\nThe default value is NAME - Page PAGE_NUMBER of TOTAL_PAGES.", "title": "Page Numbering Style", "type": "string" }, @@ -82,18 +82,18 @@ "default": { "page": { "bottom": "2 cm", - "left": "1.24 cm", - "right": "1.24 cm", + "left": "2 cm", + "right": "2 cm", "top": "2 cm" }, "section_title": { "bottom": "0.2 cm", - "top": "0.2 cm" + "top": "0.3 cm" }, "entry_area": { "date_and_location_width": "4.1 cm", "left_and_right": "0.2 cm", - "vertical_between": "0.12 cm" + "vertical_between": "0.2 cm" }, "highlights_area": { "left": "0.4 cm", @@ -101,9 +101,9 @@ "vertical_between_bullet_points": "0.10 cm" }, "header": { - "bottom": "0.2 cm", + "bottom": "0.3 cm", "horizontal_between_connections": "0.5 cm", - "vertical_between_name_and_connections": "0.2 cm" + "vertical_between_name_and_connections": "0.3 cm" } }, "description": "Page, section title, entry field, and highlights field margins.", @@ -115,7 +115,7 @@ }, "show_timespan_in": { "default": [], - "description": "The time span will be shown in the date and location column in these sections. The input should be a list of section titles as strings (case-sensitive).", + "description": "The time span will be shown in the date and location column in these sections. The input should be a list of section titles as strings (case-sensitive). The default value is an empty list, which means the time span will not be shown in any section.", "items": { "type": "string" }, @@ -379,6 +379,7 @@ "type": "object" }, "EntryAreaMargins": { + "description": "This class is a data model for the entry area margins.", "properties": { "left_and_right": { "default": "0.2 cm", @@ -388,8 +389,8 @@ "type": "string" }, "vertical_between": { - "default": "0.12 cm", - "description": "The vertical margin between entry areas. The default value is 0.12 cm.", + "default": "0.2 cm", + "description": "The vertical margin between entry areas. The default value is 0.2 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Vertical Margin Between Entry Areas", "type": "string" @@ -523,17 +524,18 @@ "type": "object" }, "HeaderMargins": { + "description": "This class is a data model for the header margins.", "properties": { "vertical_between_name_and_connections": { - "default": "0.2 cm", - "description": "The vertical margin between the name of the person and the connections. The default value is 0.2 cm.", + "default": "0.3 cm", + "description": "The vertical margin between the name of the person and the connections. The default value is 0.3 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Vertical Margin Between the Name and Connections", "type": "string" }, "bottom": { - "default": "0.2 cm", - "description": "The bottom margin of the header, i.e., the vertical margin between the connections and the first section title. The default value is 0.2 cm.", + "default": "0.3 cm", + "description": "The bottom margin of the header, i.e., the vertical margin between the connections and the first section title. The default value is 0.3 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Bottom Margin", "type": "string" @@ -551,6 +553,7 @@ "additionalProperties": false }, "HighlightsAreaMargins": { + "description": "This class is a data model for the highlights area margins.", "properties": { "top": { "default": "0.10 cm", @@ -579,6 +582,7 @@ "additionalProperties": false }, "Margins": { + "description": "This class is a data model for the margins.", "properties": { "page": { "allOf": [ @@ -589,8 +593,8 @@ "default": { "top": "2 cm", "bottom": "2 cm", - "left": "1.24 cm", - "right": "1.24 cm" + "left": "2 cm", + "right": "2 cm" }, "description": "Page margins.", "title": "Page Margins" @@ -602,7 +606,7 @@ } ], "default": { - "top": "0.2 cm", + "top": "0.3 cm", "bottom": "0.2 cm" }, "description": "Section title margins.", @@ -616,7 +620,7 @@ ], "default": { "left_and_right": "0.2 cm", - "vertical_between": "0.12 cm", + "vertical_between": "0.2 cm", "date_and_location_width": "4.1 cm" }, "description": "Entry area margins.", @@ -643,8 +647,8 @@ } ], "default": { - "vertical_between_name_and_connections": "0.2 cm", - "bottom": "0.2 cm", + "vertical_between_name_and_connections": "0.3 cm", + "bottom": "0.3 cm", "horizontal_between_connections": "0.5 cm" }, "description": "Header margins.", @@ -657,7 +661,7 @@ }, "ModerncvThemeOptions": { "additionalProperties": false, - "description": "", + "description": "This class is the data model of the theme options for the moderncv theme.", "properties": { "theme": { "const": "moderncv", @@ -680,8 +684,8 @@ "type": "string" }, "page_size": { - "default": "a4paper", - "description": "The page size of the CV. The default value is \"a4paper\".", + "default": "letterpaper", + "description": "The page size of the CV. The default value is \"letterpaper\".", "enum": [ "a4paper", "letterpaper" @@ -899,31 +903,32 @@ "type": "object" }, "PageMargins": { + "description": "This class is a data model for the page margins.", "properties": { "top": { "default": "2 cm", - "description": "The top margin of the page with units.", + "description": "The top margin of the page with units. The default value is 2 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Top Margin", "type": "string" }, "bottom": { "default": "2 cm", - "description": "The bottom margin of the page with units.", + "description": "The bottom margin of the page with units. The default value is 2 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Bottom Margin", "type": "string" }, "left": { - "default": "1.24 cm", - "description": "The left margin of the page with units.", + "default": "2 cm", + "description": "The left margin of the page with units. The default value is 2 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Left Margin", "type": "string" }, "right": { - "default": "1.24 cm", - "description": "The right margin of the page with units.", + "default": "2 cm", + "description": "The right margin of the page with units. The default value is 2 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Right Margin", "type": "string" @@ -995,7 +1000,7 @@ }, "Sb2novThemeOptions": { "additionalProperties": false, - "description": "", + "description": "This class is the data model of the theme options for the sb2nov theme.", "properties": { "font_size": { "default": "10pt", @@ -1038,8 +1043,8 @@ "type": "boolean" }, "page_numbering_style": { - "default": "NAME -- Page PAGE_NUMBER of TOTAL_PAGES", - "description": "The style of the page numbering. The following placeholders can be used:\n- NAME: The name of the person\n- PAGE_NUMBER: The current page number\n- TOTAL_PAGES: The total number of pages\nThe default value is NAME -- Page PAGE_NUMBER of TOTAL_PAGES.", + "default": "NAME - Page PAGE_NUMBER of TOTAL_PAGES", + "description": "The style of the page numbering. The following placeholders can be used:\n- NAME: The name of the person\n- PAGE_NUMBER: The current page number\n- TOTAL_PAGES: The total number of pages\nThe default value is NAME - Page PAGE_NUMBER of TOTAL_PAGES.", "title": "Page Numbering Style", "type": "string" }, @@ -1075,18 +1080,18 @@ "default": { "page": { "bottom": "2 cm", - "left": "1.24 cm", - "right": "1.24 cm", + "left": "2 cm", + "right": "2 cm", "top": "2 cm" }, "section_title": { "bottom": "0.2 cm", - "top": "0.2 cm" + "top": "0.3 cm" }, "entry_area": { "date_and_location_width": "4.1 cm", "left_and_right": "0.2 cm", - "vertical_between": "0.12 cm" + "vertical_between": "0.2 cm" }, "highlights_area": { "left": "0.4 cm", @@ -1094,9 +1099,9 @@ "vertical_between_bullet_points": "0.10 cm" }, "header": { - "bottom": "0.2 cm", + "bottom": "0.3 cm", "horizontal_between_connections": "0.5 cm", - "vertical_between_name_and_connections": "0.2 cm" + "vertical_between_name_and_connections": "0.3 cm" } }, "description": "Page, section title, entry field, and highlights field margins.", @@ -1114,17 +1119,18 @@ "type": "object" }, "SectionTitleMargins": { + "description": "This class is a data model for the section title margins.", "properties": { "top": { - "default": "0.2 cm", - "description": "The top margin of section titles. The default value is 0.2 cm.", + "default": "0.3 cm", + "description": "The top margin of section titles. The default value is 0.3 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Top Margin", "type": "string" }, "bottom": { "default": "0.2 cm", - "description": "The bottom margin of section titles. The default value is 0.2 cm.", + "description": "The bottom margin of section titles. The default value is 0.3 cm.", "pattern": "\\d+\\.?\\d* *(cm|in|pt|mm|ex|em)", "title": "Bottom Margin", "type": "string" @@ -1183,7 +1189,7 @@ "page_size": "letterpaper", "color": "#004f90", "disable_page_numbering": false, - "page_numbering_style": "NAME -- Page PAGE_NUMBER of TOTAL_PAGES", + "page_numbering_style": "NAME - Page PAGE_NUMBER of TOTAL_PAGES", "show_last_updated_date": true, "header_font_size": "30 pt", "text_alignment": "justified", @@ -1191,12 +1197,12 @@ "entry_area": { "date_and_location_width": "4.1 cm", "left_and_right": "0.2 cm", - "vertical_between": "0.12 cm" + "vertical_between": "0.2 cm" }, "header": { - "bottom": "0.2 cm", + "bottom": "0.3 cm", "horizontal_between_connections": "0.5 cm", - "vertical_between_name_and_connections": "0.2 cm" + "vertical_between_name_and_connections": "0.3 cm" }, "highlights_area": { "left": "0.4 cm", @@ -1205,13 +1211,13 @@ }, "page": { "bottom": "2 cm", - "left": "1.24 cm", - "right": "1.24 cm", + "left": "2 cm", + "right": "2 cm", "top": "2 cm" }, "section_title": { "bottom": "0.2 cm", - "top": "0.2 cm" + "top": "0.3 cm" } }, "theme": "classic",