start documenting

docs/code/data_model.md

@@ -1,2 +0,0 @@
-# data_model module
-::: rendercv.data_model

docs/code/main.md

@@ -1,2 +0,0 @@
-# __main__ module
-::: rendercv.__main__

docs/code/tinytex.md

@@ -1,2 +0,0 @@
-# tinytex module
-::: rendercv.tinytex

docs/index.md

@@ -1,17 +1,5 @@
-# Welcome to MkDocs
+# Welcome to RenderCV
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+It's a simple tool to render your CV from a YAML file.
 
-## Commands
-
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
-
-## Project layout
-
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+It's a work in progress, please come back later.

docs/reference/__main__.md

@@ -0,0 +1,2 @@
+# Main
+::: rendercv.__main__

docs/reference/data_model.md

@@ -0,0 +1,3 @@
+# Data Model
+
+::: rendercv.data_model

docs/reference/index.md

@@ -0,0 +1 @@
+Test

docs/reference/tinytex.md

@@ -0,0 +1,2 @@
+# TinyTeX
+::: rendercv.tinytex

mkdocs.yml

@@ -1,29 +1,51 @@
-site_name: My Docs
+site_name: RenderCV
+site_description: A Python application that creates a CV in PDF from a YAML/JSON input file.
+site_url: https://sinaatalay.github.io/rendercv/
+repo_name: sinaatalay/rendercv
+repo_url: https://github.com/sinaatalay/rendercv
+edit_uri: edit/main/docs/
+
 theme:
   name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/lightbulb-outline
+        name: "Switch to dark mode"
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/lightbulb
+        name: "Switch to light mode"
+  features:
+    - content.tabs.link
+    - content.code.annotate
+    - content.code.copy
 
 nav:
-  - Home: index.md
-  - About: about.md
+  - Quick Start: index.md
   - Contact: contact.md
-  - License: license.md
   - Code Reference:
-    - __main__.py: code/main.md
-    - data_model.py: code/data_model.md
-    - tinytex.py: code/tinytex.md
+      - __main__.py: reference/__main__.md
+      - data_model.py: reference/data_model.md
+      - tinytex.py: reference/tinytex.md
 
 plugins:
   - search
   - mkdocstrings:
       handlers:
         python:
+          paths:
+            - rendercv
           options:
-            show_root_heading: true
+            members_order: source
             show_bases: true
-            show_root_members_full_path: true
-            group_by_category: true
-            show_category_heading: true
-            show_symbol_type_heading: true
-            show_symbol_type_toc: true
+            docstring_section_style: list
             merge_init_into_class: true
-            docstring_style: sphinx
+            show_docstring_attributes: true
+            docstring_style: google

rendercv/__init__.py

@@ -0,0 +1,4 @@
+"""RenderCV package
+
+A Python application that creates a CV in PDF from a YAML/JSON input file.
+"""

rendercv/__main__.py

@@ -1,3 +1,7 @@
+"""
+This module is a script to run the RenderCV and generate a CV as a PDF.
+"""
+
 import os
 import json
 import logging
@@ -10,84 +14,93 @@ from ruamel.yaml import YAML
 from rendercv.data_model import RenderCVDataModel
 from rendercv.tinytex import run_latex
 
-if __name__ == "__main__":
-    # logging config:
-    logging.basicConfig(
-        level=logging.DEBUG,
-        format="%(name)s - %(levelname)s - %(message)s",
-    )
+# logging config:
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(name)s - %(levelname)s - %(message)s",
+)
 
-    workspace = os.path.dirname(os.path.dirname(__file__))
-    templateName = "classic"
-    templatePath = os.path.join(workspace, "rendercv", "templates", templateName)
-    environment = Environment(
-        loader=FileSystemLoader(templatePath),
-        trim_blocks=True,
-        lstrip_blocks=True,
-    )
-    environment.globals.update(str=str)
+workspace = os.path.dirname(os.path.dirname(__file__))
+templateName = "classic"
+templatePath = os.path.join(workspace, "rendercv", "templates", templateName)
+environment = Environment(
+    loader=FileSystemLoader(templatePath),
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+environment.globals.update(str=str)
 
-    def markdown_to_latex(value: str) -> str:
-        """
-        To be continued...
-        """
-        if not isinstance(value, str):
-            raise ValueError("markdown_to_latex should only be used on strings!")
+def markdown_to_latex(value: str) -> str:
+    """
+    Convert a markdown string to LaTeX.
 
-        # convert links
-        link = re.search(r"\[(.*)\]\((.*?)\)", value)
-        if link is not None:
-            link = link.groups()
-            oldLinkString = "[" + link[0] + "](" + link[1] + ")"
-            newLinkString = "\\hrefExternal{" + link[1] + "}{" + link[0] + "}"
+    :param value: The markdown string to convert.
+    :type value: str
+    :return: The LaTeX string.
+    :rtype: str
+    """
+    if not isinstance(value, str):
+        raise ValueError("markdown_to_latex should only be used on strings!")
 
-            value = value.replace(oldLinkString, newLinkString)
+    # convert links
+    link = re.search(r"\[(.*)\]\((.*?)\)", value)
+    if link is not None:
+        link = link.groups()
+        oldLinkString = "[" + link[0] + "](" + link[1] + ")"
+        newLinkString = "\\hrefExternal{" + link[1] + "}{" + link[0] + "}"
 
-        return value
+        value = value.replace(oldLinkString, newLinkString)
 
-    def markdown_url_to_url(value: str) -> bool:
-        """
-        To be continued...
-        """
-        if not isinstance(value, str):
-            raise ValueError("markdown_to_latex should only be used on strings!")
-        
-        link = re.search(r"\[(.*)\]\((.*?)\)", value)
-        if link is not None:
-            url = link.groups()[1]
-            return url
-        else:
-            raise ValueError(
-                "markdown_url_to_url should only be used on markdown links!"
-            )
+    return value
 
-    environment.filters["markdown_to_latex"] = markdown_to_latex
-    environment.filters["markdown_url_to_url"] = markdown_url_to_url
+def markdown_url_to_url(value: str) -> bool:
+    """
+    Convert a markdown link to a URL.
 
-    environment.block_start_string = "((*"
-    environment.block_end_string = "*))"
-    environment.variable_start_string = "<<"
-    environment.variable_end_string = ">>"
-    environment.comment_start_string = "((#"
-    environment.comment_end_string = "#))"
+    :param value: The markdown link to convert.
+    :type value: str
+    :return: The URL.
+    :rtype: str
+    """
+    if not isinstance(value, str):
+        raise ValueError("markdown_to_latex should only be used on strings!")
+    
+    link = re.search(r"\[(.*)\]\((.*?)\)", value)
+    if link is not None:
+        url = link.groups()[1]
+        return url
+    else:
+        raise ValueError(
+            "markdown_url_to_url should only be used on markdown links!"
+        )
 
-    template = environment.get_template(f"{templateName}.tex.j2")
+environment.filters["markdown_to_latex"] = markdown_to_latex
+environment.filters["markdown_url_to_url"] = markdown_url_to_url
 
-    inpur_name = "personal"
+environment.block_start_string = "((*"
+environment.block_end_string = "*))"
+environment.variable_start_string = "<<"
+environment.variable_end_string = ">>"
+environment.comment_start_string = "((#"
+environment.comment_end_string = "#))"
 
-    input_file_path = os.path.join(workspace, "tests", "inputs", f"{inpur_name}.yaml")
-    with open(input_file_path) as file:
-        yaml = YAML()
-        raw_json = yaml.load(file)
+template = environment.get_template(f"{templateName}.tex.j2")
 
-    data = RenderCVDataModel(**raw_json)
+inpur_name = "personal"
 
-    output_latex_file = template.render(design=data.design.options, cv=data.cv)
+input_file_path = os.path.join(workspace, "tests", "inputs", f"{inpur_name}.yaml")
+with open(input_file_path) as file:
+    yaml = YAML()
+    raw_json = yaml.load(file)
 
-    # Create an output file and write the rendered LaTeX code to it:
-    output_file_path = os.path.join(workspace, "tests", "outputs", f"{inpur_name}.tex")
-    os.makedirs(os.path.dirname(output_file_path), exist_ok=True)
-    with open(output_file_path, "w") as file:
-        file.write(output_latex_file)
+data = RenderCVDataModel(**raw_json)
 
-    run_latex(output_file_path)
+output_latex_file = template.render(design=data.design.options, cv=data.cv)
+
+# Create an output file and write the rendered LaTeX code to it:
+output_file_path = os.path.join(workspace, "tests", "outputs", f"{inpur_name}.tex")
+os.makedirs(os.path.dirname(output_file_path), exist_ok=True)
+with open(output_file_path, "w") as file:
+    file.write(output_latex_file)
+
+run_latex(output_file_path)

rendercv/data_model.py

@@ -1,3 +1,8 @@
+"""
+This module contains classes and functions to parse a specifically structured YAML or
+JSON to generate meaningful data for Python.
+"""
+
 from datetime import date as Date
 from datetime import datetime
 from typing import Literal
@@ -42,13 +47,13 @@ def check_spelling(sentence: str) -> str:
     """
     Check the spelling of a sentence and give warnings if there are any misspelled
     words.
-    
+
     It uses pyspellchecker. It can also guess the correct version of the
     misspelled word, but it is not used because it is very slow.
 
-    :param sentence: the sentence to be checked
+    :param sentence: The sentence to be checked.
     :type sentence: str
-    :return: the same sentence
+    :return: The same sentence.
     """
     modifiedSentence = sentence.lower()  # convert to lower case
     modifiedSentence = re.sub(
@@ -80,7 +85,15 @@ SpellCheckedString = Annotated[str, AfterValidator(check_spelling)]
 
 def compute_time_span_string(start_date: Date, end_date: Date) -> str:
     """
-    To be continued...
+    Compute the time span between two dates and return a string that represents it. For,
+    example, if the time span is 1 year and 3 months, it will return "1 year 3 months".
+
+    :param start_date: The start date.
+    :type start_date: Date
+    :param end_date: The end date.
+    :type end_date: Date
+    :return: The time span string.
+    :rtype: str
     """
     # calculate the number of days between start_date and end_date:
     timeSpanInDays = (end_date - start_date).days
@@ -197,6 +210,12 @@ class Design(BaseModel):
 
 
 class Event(BaseModel):
+    """s
+    aa
+
+    Attributes:
+        test
+    """
     start_date: Date = None
     end_date: Date | Literal["present"] = None
     date: str = None
@@ -355,9 +374,6 @@ class EducationEntry(Event):
     @computed_field
     @cached_property
     def highlight_strings(self) -> list[SpellCheckedString]:
-        """
-        To be continued...
-        """
         highlight_strings = []
 
         if self.gpa is not None:

rendercv/tinytex.py

@@ -1,7 +1,19 @@
+"""
+This module implements a handler for TinyTeX.
+"""
+
 import os
 import subprocess
 
 def run_latex(latexFilePath):
+    """
+    Run LuaLateX on the given LaTeX file and generate a PDF.
+
+    :param latexFilePath: The path to the LaTeX file to compile.
+    :type latexFilePath: str
+    :return: None
+    :rtype: None
+    """
     latexFilePath = os.path.normpath(latexFilePath)
     latexFile = os.path.basename(latexFilePath)