docs: update reference

docs/developer_guide/index.md

@@ -56,15 +56,18 @@ The flowchart below illustrates the general operations of RenderCV. A detailed d
 
 ```mermaid
 flowchart TD
+    subgraph rendercv.data
     A[YAML Input File] --parsing with ruamel.yaml package--> B(Python Dictionary)
     B --validation with pydantic package--> C((Pydantic Object))
-    C --> D[LaTeX File]
-    C --> E[Markdown File]
-    E --markdown package--> K[HTML FIle]
-    D --TinyTeX--> L[PDF File]
+    end
+    subgraph rendercv.renderer
+    C --> AA
+    E[Markdown File] --markdown package--> K[HTML FIle]
+    D[LaTeX File] --TinyTeX--> L[PDF File]
     L --PyMuPDF package--> Z[PNG Files]
     AA[(Jinja2 Templates)] --> D
     AA[(Jinja2 Templates)] --> E
+    end
 ```
 
 ## Available Commands

docs/reference/cli.md

@@ -1,3 +0,0 @@
-# `cli.py`
-
-::: rendercv.cli

docs/reference/cli/commands.md

@@ -0,0 +1,3 @@
+# `rendercv.cli.commands`
+
+::: rendercv.cli.commands

docs/reference/cli/index.md

@@ -0,0 +1,3 @@
+# `rendercv.cli`
+
+::: rendercv.cli

docs/reference/cli/printer.md

@@ -0,0 +1,3 @@
+# `rendercv.cli.printer`
+
+::: rendercv.cli.printer

docs/reference/cli/utilities.md

@@ -0,0 +1,3 @@
+# `rendercv.cli.utilities`
+
+::: rendercv.cli.utilities

docs/reference/data/generator.md

@@ -0,0 +1,3 @@
+# `rendercv.data.generator`
+
+::: rendercv.data.generator

docs/reference/data/index.md

@@ -0,0 +1,3 @@
+# `rendercv.data`
+
+::: rendercv.data

docs/reference/data/models/base.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models.base`
+
+::: rendercv.data.models.base

docs/reference/data/models/computers.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models.computers`
+
+::: rendercv.data.models.computers

docs/reference/data/models/curriculum_vitae.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models.curriculum_vitae`
+
+::: rendercv.data.models.curriculum_vitae

docs/reference/data/models/design.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models.design`
+
+::: rendercv.data.models.design

docs/reference/data/models/entry_types.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models.entry_types`
+
+::: rendercv.data.models.entry_types

docs/reference/data/models/index.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models`
+
+::: rendercv.data.models

docs/reference/data/models/locale_catalog.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models.locale_catalog`
+
+::: rendercv.data.models.locale_catalog

docs/reference/data/models/rendercv_data_model.md

@@ -0,0 +1,3 @@
+# `rendercv.data.models.rendercv_data_model`
+
+::: rendercv.data.models.rendercv_data_model

docs/reference/data/reader.md

@@ -0,0 +1,3 @@
+# `rendercv.data.reader`
+
+::: rendercv.data.reader

docs/reference/data_models.md

@@ -1,3 +0,0 @@
-# `data_models.py`
-
-::: rendercv.data_models

docs/reference/index.md

@@ -4,11 +4,11 @@
 
 In this section, you can find how RenderCV's components are structured and how they interact with each other.
 
-- [cli.py](cli.md) – This module contains all the command-line interface (CLI) related code for RenderCV.
-- [data_models.py](data_models.md) – This module contains classes and functions to parse and validate RenderCV's input YAML.
-- [renderer.py](renderer.md) – This module contains utilities for generating $\LaTeX$, Markdown, and HTML files, as well as running TinyTeX for RenderCV.
-- [themes](themes/index.md) – This package contains all the built-in themes of RenderCV.
-    - [classic](themes/classic.md)
-    - [engineeringresumes](themes/engineeringresumes.md)
-    - [sb2nov](themes/sb2nov.md)
-    - [moderncv](themes/moderncv.md)
+- [`cli`](cli/index.md) – This package contains all the command-line interface (CLI) related code for RenderCV.
+- [`data`](data/index.md) – This package contains classes and functions to parse and validate a YAML input file.
+- [`renderer`](renderer/index.md) – This package contains utilities for generating the output files.
+- [`themes`](themes/index.md) – This package contains all the built-in themes of RenderCV.
+    - [`classic`](themes/classic.md)
+    - [`engineeringresumes`](themes/engineeringresumes.md)
+    - [`sb2nov`](themes/sb2nov.md)
+    - [`moderncv`](themes/moderncv.md)

docs/reference/renderer.md

@@ -1,3 +0,0 @@
-# `renderer.py`
-
-::: rendercv.renderer

docs/reference/renderer/index.md

@@ -0,0 +1,3 @@
+# `rendercv.renderer`
+
+::: rendercv.renderer

docs/reference/renderer/renderer.md

@@ -0,0 +1,3 @@
+# `rendercv.renderer.renderer`
+
+::: rendercv.renderer.renderer

docs/reference/renderer/templater.md

@@ -0,0 +1,3 @@
+# `rendercv.renderer.templater`
+
+::: rendercv.renderer.templater

docs/update_entry_figures.py

@@ -14,8 +14,8 @@ from typing import Any
 import pdfCropMargins
 import ruamel.yaml
 
-import rendercv.data as dm
-import rendercv.renderer as r
+import rendercv.data as data
+import rendercv.renderer as renderer
 
 repository_root = pathlib.Path(__file__).parent.parent
 rendercv_path = repository_root / "rendercv"
@@ -127,7 +127,7 @@ def define_env(env):
                     "alt_text": f"{proper_entry_name} in {theme}",
                     "theme": theme,
                 }
-                for theme in dm.available_themes
+                for theme in data.available_themes
             ],
         }
 
@@ -136,7 +136,7 @@ def define_env(env):
     # for theme templates reference docs:
     themes_path = rendercv_path / "themes"
     theme_templates = dict()
-    for theme in dm.available_themes:
+    for theme in data.available_themes:
         theme_templates[theme] = dict()
         for theme_file in themes_path.glob(f"{theme}/*.tex"):
             theme_templates[theme][
@@ -146,12 +146,12 @@ def define_env(env):
     env.variables["theme_templates"] = theme_templates
 
     # available themes strings (put available themes between ``)
-    themes = [f"`{theme}`" for theme in dm.available_themes]
+    themes = [f"`{theme}`" for theme in data.available_themes]
     env.variables["available_themes"] = ", ".join(themes)
 
     # available social networks strings (put available social networks between ``)
     social_networks = [
-        f"`{social_network}`" for social_network in dm.available_social_networks
+        f"`{social_network}`" for social_network in data.available_social_networks
     ]
     env.variables["available_social_networks"] = ", ".join(social_networks)
 
@@ -160,15 +160,15 @@ def generate_entry_figures():
     """Generate an image for each entry type and theme."""
     # Generate PDF figures for each entry type and theme
     entries = {
-        "education_entry": dm.EducationEntry(**education_entry),
-        "experience_entry": dm.ExperienceEntry(**experience_entry),
-        "normal_entry": dm.NormalEntry(**normal_entry),
-        "publication_entry": dm.PublicationEntry(**publication_entry),
-        "one_line_entry": dm.OneLineEntry(**one_line_entry),
+        "education_entry": data.EducationEntry(**education_entry),
+        "experience_entry": data.ExperienceEntry(**experience_entry),
+        "normal_entry": data.NormalEntry(**normal_entry),
+        "publication_entry": data.PublicationEntry(**publication_entry),
+        "one_line_entry": data.OneLineEntry(**one_line_entry),
         "text_entry": f"{text_entry}",
-        "bullet_entry": dm.BulletEntry(**bullet_entry),
+        "bullet_entry": data.BulletEntry(**bullet_entry),
     }
-    themes = dm.available_themes
+    themes = data.available_themes
 
     with tempfile.TemporaryDirectory() as temporary_directory:
         # create a temporary directory:
@@ -186,18 +186,18 @@ def generate_entry_figures():
 
             for entry_type, entry in entries.items():
                 # Create the data model with only one section and one entry
-                data_model = dm.RenderCVDataModel(
+                data_model = data.RenderCVDataModel(
                     **{
-                        "cv": dm.CurriculumVitae(sections={entry_type: [entry]}),
+                        "cv": data.CurriculumVitae(sections={entry_type: [entry]}),
                         "design": design_dictionary,
                     }
                 )
 
                 # Render:
-                latex_file_path = r.render_a_latex_file_and_copy_theme_files(
+                latex_file_path = renderer.render_a_latex_file_and_copy_theme_files(
                     data_model, temporary_directory_path
                 )
-                pdf_file_path = r.render_pdf_from_latex(latex_file_path)
+                pdf_file_path = renderer.render_pdf_from_latex(latex_file_path)
 
                 # Prepare the output directory and file path:
                 output_directory = image_assets_directory / theme
@@ -228,7 +228,7 @@ def generate_entry_figures():
                 )
 
                 # Convert pdf to an image
-                png_file_path = r.render_a_markdown_file(output_pdf_file_path)[0]
+                png_file_path = renderer.render_a_markdown_file(output_pdf_file_path)[0]
                 desired_png_file_path = output_pdf_file_path.with_suffix(".png")
 
                 # If the image exists, remove it

docs/update_examples.py

@@ -5,8 +5,8 @@ import pathlib
 import shutil
 
 import rendercv.cli as cli
-import rendercv.data as dm
-import rendercv.renderer as r
+import rendercv.data as data
+import rendercv.renderer as renderer
 
 repository_root = pathlib.Path(__file__).parent.parent
 rendercv_path = repository_root / "rendercv"
@@ -22,7 +22,7 @@ def generate_examples():
         examples_directory_path.mkdir()
 
     os.chdir(examples_directory_path)
-    themes = dm.available_themes
+    themes = data.available_themes
     for theme in themes:
         cli.cli_command_new(
             "John Doe",
@@ -61,7 +61,7 @@ def generate_examples():
         shutil.rmtree(rendercv_output_directory)
 
         # convert first page of the pdf to an image:
-        png_file_paths = r.render_a_markdown_file(new_pdf_file_path)
+        png_file_paths = renderer.render_a_markdown_file(new_pdf_file_path)
         firt_page_png_file_path = png_file_paths[0]
         if len(png_file_paths) > 1:
             # remove the other pages

docs/update_schema.py

@@ -2,7 +2,7 @@
 
 import pathlib
 
-import rendercv.data as dm
+import rendercv.data as data
 
 repository_root = pathlib.Path(__file__).parent.parent
 
@@ -10,7 +10,7 @@ repository_root = pathlib.Path(__file__).parent.parent
 def generate_schema():
     """Generate the schema."""
     json_schema_file_path = repository_root / "schema.json"
-    dm.generate_json_schema_file(json_schema_file_path)
+    data.generate_json_schema_file(json_schema_file_path)
 
 
 if __name__ == "__main__":

mkdocs.yaml

@@ -61,9 +61,28 @@ nav:
       - FAQ: developer_guide/faq.md
   - Reference:
       - Reference: reference/index.md
-      - cli.py: reference/cli.md
-      - data_models.py: reference/data_models.md
-      - renderer.py: reference/renderer.md
+      - cli:
+          - cli: reference/cli/index.md
+          - commands: reference/cli/commands.md
+          - printer: reference/cli/printer.md
+          - utilities: reference/cli/utilities.md
+      - data:
+          - data: reference/data/index.md
+          - models:
+              - models: reference/data/models/index.md
+              - base: reference/data/models/base.md
+              - computers: reference/data/models/computers.md
+              - entry_types: reference/data/models/entry_types.md
+              - curriculum_vitae: reference/data/models/curriculum_vitae.md
+              - design: reference/data/models/design.md
+              - locale_catalog: reference/data/models/locale_catalog.md
+              - rendercv_data_model: reference/data/models/rendercv_data_model.md
+          - generator: reference/data/generator.md
+          - reader: reference/data/reader.md
+      - renderer:
+          - renderer: reference/renderer/index.md
+          - renderer: reference/renderer/renderer.md
+          - templater: reference/renderer/templater.md
       - themes:
           - themes: reference/themes/index.md
           - classic: reference/themes/classic.md

rendercv/cli/utilities.py

@@ -172,7 +172,7 @@ def get_error_message_and_location_and_value_from_a_custom_error(
     error_string: str,
 ) -> tuple[Optional[str], Optional[str], Optional[str]]:
     """Look at a string and figure out if it's a custom error message that has been
-    sent from [`data_models.py`](data_models.md). If it is, then return the custom
+    sent from `rendercv.data.reader.read_input_file`. If it is, then return the custom
     message, location, and the input value.
 
     This is done because sometimes we raise an error about a specific field in the model

rendercv/data/__init__.py

@@ -31,7 +31,9 @@ from .models import (
     SocialNetwork,
     available_social_networks,
     available_theme_options,
+    available_themes,
     format_date,
+    SectionContents,
 )
 from .reader import read_input_file
 
@@ -56,4 +58,5 @@ __all__ = [
     "format_date",
     "Entry",
     "available_social_networks",
+    "SectionContents",
 ]

rendercv/data/models/__init__.py

@@ -21,8 +21,13 @@ modules, each containing a different group of data models.
 """
 
 from .computers import format_date
-from .curriculum_vitae import CurriculumVitae, SocialNetwork, available_social_networks
-from .design import available_theme_options
+from .curriculum_vitae import (
+    CurriculumVitae,
+    SocialNetwork,
+    available_social_networks,
+    SectionContents,
+)
+from .design import available_theme_options, available_themes
 from .entry_types import (
     BulletEntry,
     EducationEntry,
@@ -50,4 +55,6 @@ __all__ = [
     "format_date",
     "Entry",
     "available_social_networks",
+    "SectionContents",
+    "available_themes",
 ]

rendercv/data/models/design.py

@@ -10,10 +10,10 @@ from typing import Annotated, Any, Type
 
 import pydantic
 
-from ...renderer.themes.classic import ClassicThemeOptions
-from ...renderer.themes.engineeringresumes import EngineeringresumesThemeOptions
-from ...renderer.themes.moderncv import ModerncvThemeOptions
-from ...renderer.themes.sb2nov import Sb2novThemeOptions
+from ...themes.classic import ClassicThemeOptions
+from ...themes.engineeringresumes import EngineeringresumesThemeOptions
+from ...themes.moderncv import ModerncvThemeOptions
+from ...themes.sb2nov import Sb2novThemeOptions
 from . import entry_types
 from .base import RenderCVBaseModel
 
@@ -175,3 +175,5 @@ available_theme_options = {
     "sb2nov": Sb2novThemeOptions,
     "engineeringresumes": EngineeringresumesThemeOptions,
 }
+
+available_themes = list(available_theme_options.keys())

rendercv/data/models/entry_types.py

@@ -1,5 +1,5 @@
 """
-`rendercv.models.data.entry_types` module contains the data models of all the available
+The `rendercv.models.data.entry_types` module contains the data models of all the available
 entry types in RenderCV.
 """
 
@@ -85,7 +85,9 @@ def validate_and_adjust_dates_for_an_entry(
     """Check if the dates are provided correctly and make the necessary adjustments.
 
     Args:
-        entry (EntryBase): The entry to validate its dates.
+        start_date (StartDate): The start date of the event.
+        end_date (EndDate): The end date of the event.
+        date (ArbitraryDate): The date of the event.
     Returns:
         EntryBase: The validated
     """

rendercv/data/models/locale_catalog.py

@@ -1,6 +1,6 @@
 """
-`rendercv.models.locale_catalog` module contains the data model of the `locale_catalog`
-field of the input file.
+The `rendercv.models.locale_catalog` module contains the data model of the
+`locale_catalog` field of the input file.
 """
 
 from typing import Annotated, Optional

rendercv/data/models/rendercv_data_model.py

@@ -7,7 +7,7 @@ from typing import Optional
 
 import pydantic
 
-from ...renderer.themes.classic import ClassicThemeOptions
+from ...themes.classic import ClassicThemeOptions
 
 # Disable Pydantic warnings:
 # warnings.filterwarnings("ignore")

rendercv/renderer/renderer.py

@@ -14,8 +14,8 @@ from typing import Optional
 import fitz
 import markdown
 
-from .. import data as dm
-from . import templater as tp
+from .. import data
+from . import templater
 
 
 def copy_theme_files_to_output_directory(
@@ -31,7 +31,7 @@ def copy_theme_files_to_output_directory(
         theme_name (str): The name of the theme.
         output_directory_path (pathlib.Path): Path to the output directory.
     """
-    if theme_name in dm.available_themes:
+    if theme_name in data.available_themes:
         theme_directory_path = importlib.resources.files(
             f"rendercv.themes.{theme_name}"
         )
@@ -69,7 +69,7 @@ def copy_theme_files_to_output_directory(
 
 
 def render_a_latex_file(
-    rendercv_data_model: dm.RenderCVDataModel, output_directory: pathlib.Path
+    rendercv_data_model: data.RenderCVDataModel, output_directory: pathlib.Path
 ) -> pathlib.Path:
     """Render the $\\LaTeX$ file with the given data model and write it to the output
     directory.
@@ -84,8 +84,8 @@ def render_a_latex_file(
     if not output_directory.is_dir():
         output_directory.mkdir(parents=True)
 
-    jinja2_environment = tp.setup_jinja2_environment()
-    latex_file_object = tp.LaTeXFile(
+    jinja2_environment = templater.setup_jinja2_environment()
+    latex_file_object = templater.LaTeXFile(
         rendercv_data_model,
         jinja2_environment,
     )
@@ -98,7 +98,7 @@ def render_a_latex_file(
 
 
 def render_a_markdown_file(
-    rendercv_data_model: dm.RenderCVDataModel, output_directory: pathlib.Path
+    rendercv_data_model: data.RenderCVDataModel, output_directory: pathlib.Path
 ) -> pathlib.Path:
     """Render the Markdown file with the given data model and write it to the output
     directory.
@@ -113,8 +113,8 @@ def render_a_markdown_file(
     if not output_directory.is_dir():
         output_directory.mkdir(parents=True)
 
-    jinja2_environment = tp.setup_jinja2_environment()
-    markdown_file_object = tp.MarkdownFile(
+    jinja2_environment = templater.setup_jinja2_environment()
+    markdown_file_object = templater.MarkdownFile(
         rendercv_data_model,
         jinja2_environment,
     )
@@ -127,7 +127,7 @@ def render_a_markdown_file(
 
 
 def render_a_latex_file_and_copy_theme_files(
-    rendercv_data_model: dm.RenderCVDataModel, output_directory: pathlib.Path
+    rendercv_data_model: data.RenderCVDataModel, output_directory: pathlib.Path
 ) -> pathlib.Path:
     """Render the $\\LaTeX$ file with the given data model in the output directory and
     copy the auxiliary theme files to the output directory.
@@ -304,7 +304,7 @@ def render_html_from_markdown(markdown_file_path: pathlib.Path) -> pathlib.Path:
     else:
         title = title.group(1)
 
-    jinja2_environment = tp.setup_jinja2_environment()
+    jinja2_environment = templater.setup_jinja2_environment()
     html_template = jinja2_environment.get_template("main.j2.html")
     html = html_template.render(html_body=html_body, title=title)
 

rendercv/renderer/templater.py

@@ -12,7 +12,7 @@ from typing import Any, Optional
 
 import jinja2
 
-from .. import data as dm
+from .. import data
 
 
 class TemplatedFile:
@@ -28,7 +28,7 @@ class TemplatedFile:
 
     def __init__(
         self,
-        data_model: dm.RenderCVDataModel,
+        data_model: data.RenderCVDataModel,
         environment: jinja2.Environment,
     ):
         self.cv = data_model.cv
@@ -40,7 +40,7 @@ class TemplatedFile:
         theme_name: str,
         template_name: str,
         extension: str,
-        entry: Optional[dm.Entry] = None,
+        entry: Optional[data.Entry] = None,
         **kwargs,
     ) -> str:
         """Template one of the files in the `themes` directory.
@@ -75,7 +75,7 @@ class TemplatedFile:
             cv=self.cv,
             design=self.design,
             entry=entry,
-            today=dm.format_date(Date.today(), use_full_name=True),
+            today=data.format_date(Date.today(), use_full_name=True),
             **kwargs,
         )
 
@@ -97,7 +97,7 @@ class LaTeXFile(TemplatedFile):
 
     def __init__(
         self,
-        data_model: dm.RenderCVDataModel,
+        data_model: data.RenderCVDataModel,
         environment: jinja2.Environment,
     ):
         latex_file_data_model = copy.deepcopy(data_model)
@@ -152,7 +152,7 @@ class LaTeXFile(TemplatedFile):
     def template(
         self,
         template_name: str,
-        entry: Optional[dm.Entry] = None,
+        entry: Optional[data.Entry] = None,
         **kwargs,
     ) -> str:
         """Template one of the files in the `themes` directory.
@@ -242,7 +242,7 @@ class MarkdownFile(TemplatedFile):
     def template(
         self,
         template_name: str,
-        entry: Optional[dm.Entry] = None,
+        entry: Optional[data.Entry] = None,
         **kwargs,
     ) -> str:
         """Template one of the files in the `themes` directory.
@@ -461,8 +461,8 @@ def markdown_to_latex(markdown_string: str) -> str:
 
 
 def transform_markdown_sections_to_latex_sections(
-    sections: dict[str, dm.SectionInput],
-) -> Optional[dict[str, dm.SectionInput]]:
+    sections: dict[str, data.SectionContents],
+) -> Optional[dict[str, data.SectionContents]]:
     """
     Recursively loop through sections and convert all the Markdown strings (user input
     is in Markdown format) to $\\LaTeX$ strings. Also, escape special $\\LaTeX$
@@ -531,14 +531,9 @@ def make_matched_part_something(
     whole string will be made something.
 
     Warning:
-        This function shouldn't be used directly. Use
-        [make_matched_part_bold][rendercv.renderer.make_matched_part_bold],
-        [make_matched_part_underlined][rendercv.renderer.make_matched_part_underlined],
-        [make_matched_part_italic][rendercv.renderer.make_matched_part_italic],
-        or
-        [make_matched_part_non_line_breakable][rendercv.renderer.make_matched_part_non_line_breakable]
-        instead.
-
+        This function shouldn't be used directly. Use `make_matched_part_bold`,
+        `make_matched_part_underlined`, `make_matched_part_italic`, or
+        `make_matched_part_non_line_breakable instead.
     Args:
         value (str): The string to make something.
         something (str): The $\\LaTeX$ command to use.