From 23fd145a76d9a78c3facd80a14d1784e0f422741 Mon Sep 17 00:00:00 2001 From: Sina Atalay Date: Sun, 10 Sep 2023 21:54:36 +0200 Subject: [PATCH] start documenting --- docs/contact.md | 0 docs/index.md | 18 +- docs/{code/main.md => reference/__main__.md} | 2 +- docs/{code => reference}/data_model.md | 3 +- docs/reference/index.md | 1 + docs/{code => reference}/tinytex.md | 2 +- mkdocs.yml | 50 ++++-- rendercv/__init__.py | 4 + rendercv/__main__.py | 175 ++++++++++--------- rendercv/data_model.py | 30 +++- rendercv/tinytex.py | 12 ++ 11 files changed, 177 insertions(+), 120 deletions(-) create mode 100644 docs/contact.md rename docs/{code/main.md => reference/__main__.md} (53%) rename docs/{code => reference}/data_model.md (53%) create mode 100644 docs/reference/index.md rename docs/{code => reference}/tinytex.md (54%) diff --git a/docs/contact.md b/docs/contact.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/index.md b/docs/index.md index 000ea345..e224ad5e 100644 --- a/docs/index.md +++ b/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. \ No newline at end of file diff --git a/docs/code/main.md b/docs/reference/__main__.md similarity index 53% rename from docs/code/main.md rename to docs/reference/__main__.md index aeda5ba0..d98792ff 100644 --- a/docs/code/main.md +++ b/docs/reference/__main__.md @@ -1,2 +1,2 @@ -# __main__ module +# Main ::: rendercv.__main__ \ No newline at end of file diff --git a/docs/code/data_model.md b/docs/reference/data_model.md similarity index 53% rename from docs/code/data_model.md rename to docs/reference/data_model.md index 3d27dbaf..97a29276 100644 --- a/docs/code/data_model.md +++ b/docs/reference/data_model.md @@ -1,2 +1,3 @@ -# data_model module +# Data Model + ::: rendercv.data_model \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 00000000..8318c86b --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1 @@ +Test \ No newline at end of file diff --git a/docs/code/tinytex.md b/docs/reference/tinytex.md similarity index 54% rename from docs/code/tinytex.md rename to docs/reference/tinytex.md index b67de2f2..2b4420d0 100644 --- a/docs/code/tinytex.md +++ b/docs/reference/tinytex.md @@ -1,2 +1,2 @@ -# tinytex module +# TinyTeX ::: rendercv.tinytex \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 17685bd8..9fbcae7b 100644 --- a/mkdocs.yml +++ b/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 \ No newline at end of file + show_docstring_attributes: true + docstring_style: google \ No newline at end of file diff --git a/rendercv/__init__.py b/rendercv/__init__.py index e69de29b..545583e5 100644 --- a/rendercv/__init__.py +++ b/rendercv/__init__.py @@ -0,0 +1,4 @@ +"""RenderCV package + +A Python application that creates a CV in PDF from a YAML/JSON input file. +""" \ No newline at end of file diff --git a/rendercv/__main__.py b/rendercv/__main__.py index 4419e7df..6a20a29a 100644 --- a/rendercv/__main__.py +++ b/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 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", - ) - - 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!") - - # 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] + "}" - - value = value.replace(oldLinkString, newLinkString) - - return value - - 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!" - ) - - environment.filters["markdown_to_latex"] = markdown_to_latex - environment.filters["markdown_url_to_url"] = markdown_url_to_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 = "#))" - - template = environment.get_template(f"{templateName}.tex.j2") - - inpur_name = "personal" - - 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) - - data = RenderCVDataModel(**raw_json) - - 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) +# 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) + +def markdown_to_latex(value: str) -> str: + """ + Convert a markdown string to LaTeX. + + :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!") + + # 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] + "}" + + value = value.replace(oldLinkString, newLinkString) + + return value + +def markdown_url_to_url(value: str) -> bool: + """ + Convert a markdown link to a URL. + + :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!" + ) + +environment.filters["markdown_to_latex"] = markdown_to_latex +environment.filters["markdown_url_to_url"] = markdown_url_to_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 = "#))" + +template = environment.get_template(f"{templateName}.tex.j2") + +inpur_name = "personal" + +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) + +data = RenderCVDataModel(**raw_json) + +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) diff --git a/rendercv/data_model.py b/rendercv/data_model.py index 628c27bf..0d08ea8a 100644 --- a/rendercv/data_model.py +++ b/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 @@ def check_spelling(sentence: str) -> str: 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: diff --git a/rendercv/tinytex.py b/rendercv/tinytex.py index 921338a8..7afbdb9e 100644 --- a/rendercv/tinytex.py +++ b/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)