From 8dcbb66a8bc6cbe5f9ba0e59da462f23d6fc0bcb Mon Sep 17 00:00:00 2001 From: Sina Atalay Date: Tue, 23 Jul 2024 18:12:44 +0300 Subject: [PATCH] docs: improve --- docs/update_entry_figures.py | 123 +++++------------- docs/user_guide/sample_entries.yaml | 51 ++++++++ .../structure_of_the_yaml_input_file.md | 44 +++++-- 3 files changed, 119 insertions(+), 99 deletions(-) create mode 100644 docs/user_guide/sample_entries.yaml diff --git a/docs/update_entry_figures.py b/docs/update_entry_figures.py index bc1e223d..914ca46f 100644 --- a/docs/update_entry_figures.py +++ b/docs/update_entry_figures.py @@ -9,82 +9,27 @@ import io import pathlib import shutil import tempfile -from typing import Any import pdfCropMargins import ruamel.yaml import rendercv.data as data import rendercv.renderer as renderer +import pydantic repository_root = pathlib.Path(__file__).parent.parent rendercv_path = repository_root / "rendercv" image_assets_directory = pathlib.Path(__file__).parent / "assets" / "images" -# The entries below will be pasted into the documentation as YAML, and their -# corresponding figures will be generated with this script. -education_entry = { - "institution": "Boğaziçi University", - "location": "Istanbul, Turkey", - "degree": "BS", - "area": "Mechanical Engineering", - "start_date": "2015-09", - "end_date": "2020-06", - "highlights": [ - "GPA: 3.24/4.00 ([Transcript](https://example.com))", - "Awards: Dean's Honor List, Sportsperson of the Year", - ], -} -experience_entry = { - "company": "Some Company", - "location": "TX, USA", - "position": "Software Engineer", - "start_date": "2020-07", - "end_date": "2021-08-12", - "highlights": [ - ( - "Developed an [IOS application](https://example.com) that has received" - " more than **100,000 downloads**." - ), - "Managed a team of **5** engineers.", - ], -} - -normal_entry = { - "name": "Some Project", - "date": "2021-09", - "highlights": [ - "Developed a web application with **React** and **Django**.", - "Implemented a **RESTful API**", - ], -} - -publication_entry = { - "title": ( - "Magneto-Thermal Thin Shell Approximation for 3D Finite Element Analysis of" - " No-Insulation Coils" - ), - "authors": ["J. Doe", "***H. Tom***", "S. Doe", "A. Andsurname"], - "date": "2021-12-08", - "journal": "IEEE Transactions on Applied Superconductivity", - "doi": "10.1109/TASC.2023.3340648", -} - -one_line_entry = { - "label": "Programming", - "details": "Python, C++, JavaScript, MATLAB", -} - -bullet_entry = { - "bullet": "This is a bullet entry.", -} - -text_entry = ( - "This is a *TextEntry*. It is only a text and can be useful for sections like" - " **Summary**. To showcase the TextEntry completely, this sentence is added, but it" - " doesn't contain any information." -) +class SampleEntries(pydantic.BaseModel): + education_entry: data.EducationEntry + experience_entry: data.ExperienceEntry + normal_entry: data.NormalEntry + publication_entry: data.PublicationEntry + one_line_entry: data.OneLineEntry + bullet_entry: data.BulletEntry + text_entry: str def dictionary_to_yaml(dictionary: dict): @@ -106,24 +51,20 @@ def dictionary_to_yaml(dictionary: dict): def define_env(env): # See https://mkdocs-macros-plugin.readthedocs.io/en/latest/macros/ - entries = [ - "education_entry", - "experience_entry", - "normal_entry", - "publication_entry", - "one_line_entry", - "bullet_entry", - "text_entry", - ] + sample_entries = data.read_a_yaml_file( + repository_root / "docs" / "user_guide" / "sample_entries.yaml" + ) + # validate the parsed dictionary by creating an instance of SampleEntries: + SampleEntries(**sample_entries) entries_showcase = dict() - for entry in entries: - proper_entry_name = entry.replace("_", " ").title() + for entry_name, entry in sample_entries.items(): + proper_entry_name = entry_name.replace("_", " ").title().replace(" ", "") entries_showcase[proper_entry_name] = { - "yaml": dictionary_to_yaml(eval(entry)), + "yaml": dictionary_to_yaml(entry), "figures": [ { - "path": f"../assets/images/{theme}/{entry}.png", + "path": f"../assets/images/{theme}/{entry_name}.png", "alt_text": f"{proper_entry_name} in {theme}", "theme": theme, } @@ -182,15 +123,10 @@ def define_env(env): 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": 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": data.BulletEntry(**bullet_entry), - } + entries = data.read_a_yaml_file( + rendercv_path / "docs" / "user_guide" / "sample_entries.yaml" + ) + entries = SampleEntries(**entries) themes = data.available_themes with tempfile.TemporaryDirectory() as temporary_directory: @@ -207,11 +143,22 @@ def generate_entry_figures(): del design_dictionary["disable_page_numbering"] del design_dictionary["disable_last_updated_date"] - for entry_type, entry in entries.items(): + entry_types = [ + "education_entry", + "experience_entry", + "normal_entry", + "publication_entry", + "one_line_entry", + "bullet_entry", + "text_entry", + ] + for entry_type in entry_types: # Create data model with only one section and one entry data_model = data.RenderCVDataModel( **{ - "cv": data.CurriculumVitae(sections={entry_type: [entry]}), + "cv": data.CurriculumVitae( + sections={entry_type: [getattr(entries, entry_type)]} + ), "design": design_dictionary, } ) diff --git a/docs/user_guide/sample_entries.yaml b/docs/user_guide/sample_entries.yaml new file mode 100644 index 00000000..f4396412 --- /dev/null +++ b/docs/user_guide/sample_entries.yaml @@ -0,0 +1,51 @@ +education_entry: + institution: Boğaziçi University + location: Istanbul, Turkey + degree: BS + area: Mechanical Engineering + start_date: 2015-09 + end_date: 2020-06 + highlights: + - "GPA: 3.24/4.00 ([Transcript](https://example.com))" + - "Awards: Dean's Honor List, Sportsperson of the Year" + +experience_entry: + company: Some Company + location: TX, USA + position: Software Engineer + start_date: 2020-07 + end_date: "2021-08-12" + highlights: + - Developed an [IOS application](https://example.com) that has + received more than **100,000 downloads**. + - Managed a team of **5** engineers. + +normal_entry: + name: Some Project + date: 2021-09 + highlights: + - Developed a web application with **React** and **Django**. + - Implemented a **RESTful API** + +publication_entry: + title: Magneto-Thermal Thin Shell Approximation for 3D Finite + Element Analysis of No-Insulation Coils + authors: + - J. Doe + - "***H. Tom***" + - S. Doe + - A. Andsurname + date: "2021-12-08" + journal: IEEE Transactions on Applied Superconductivity + doi: 10.1109/TASC.2023.3340648 + +one_line_entry: + label: Programming + details: Python, C++, JavaScript, MATLAB + +bullet_entry: + bullet: This is a bullet entry. + +text_entry: This is a *TextEntry*. It is only a text and can be useful for + sections like **Summary**. To showcase the TextEntry completely, + this sentence is added, but it doesn't contain any information. diff --git a/docs/user_guide/structure_of_the_yaml_input_file.md b/docs/user_guide/structure_of_the_yaml_input_file.md index 11d6a8d8..0238e9c6 100644 --- a/docs/user_guide/structure_of_the_yaml_input_file.md +++ b/docs/user_guide/structure_of_the_yaml_input_file.md @@ -125,7 +125,7 @@ Each entry type is a different object (a dictionary). Below, you can find all th {% for entry_name, entry in showcase_entries.items() %} #### {{ entry_name }} -{% if entry_name == "Education Entry" %} +{% if entry_name == "EducationEntry" %} **Mandatory Fields:** @@ -141,7 +141,7 @@ Each entry type is a different object (a dictionary). Below, you can find all th - `date`: The date as a custom string or in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format. This will override `start_date` and `end_date`. - `highlights`: A list of bullet points. -{% elif entry_name == "Experience Entry" %} +{% elif entry_name == "ExperienceEntry" %} **Mandatory Fields:** @@ -156,7 +156,7 @@ Each entry type is a different object (a dictionary). Below, you can find all th - `date`: The date as a custom string or in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format. This will override `start_date` and `end_date`. - `highlights`: A list of bullet points. -{% elif entry_name == "Publication Entry" %} +{% elif entry_name == "PublicationEntry" %} **Mandatory Fields:** @@ -169,7 +169,7 @@ Each entry type is a different object (a dictionary). Below, you can find all th - `journal`: The journal of the publication. - `date`: The date as a custom string or in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format. -{% elif entry_name == "Normal Entry" %} +{% elif entry_name == "NormalEntry" %} **Mandatory Fields:** @@ -189,15 +189,15 @@ Each entry type is a different object (a dictionary). Below, you can find all th **Mandatory Fields:** - `label`: The label of the entry. -- `details`: The value of the entry. +- `details`: The details of the entry. -{% elif entry_name == "Bullet Entry" %} +{% elif entry_name == "BulletEntry" %} **Mandatory Fields:** - `bullet`: The bullet point. -{% elif entry_name == "Text Entry" %} +{% elif entry_name == "TextEntry" %} **Mandatory Fields:** @@ -214,9 +214,21 @@ Each entry type is a different object (a dictionary). Below, you can find all th {% endfor %} {% endfor %} -#### Using additional custom keys in the entries +#### Markdown Syntax -RenderCV allows the usage of extra keys in the entries. For instance, the following is an `ExperienceEntry` containing an additional key, `summary`. +All the fields in the entries support Markdown syntax. + +You can make anything bold by surrounding it with `**`, italic with `*`, and links with `[]()`, as shown below. + +```yaml +company: "**This will be bold**, *this will be italic*, + and [this will be a link](https://example.com)." +... +``` + +### Using arbitrary keys + +RenderCV allows the usage of any number of extra keys in the entries. For instance, the following is an `ExperienceEntry` containing an additional key, `an_arbitrary_key`. ```yaml hl_lines="6" company: Some Company @@ -224,13 +236,21 @@ location: TX, USA position: Software Engineer start_date: 2020-07 end_date: '2021-08-12' -summary: Developed an [IOS application](https://example.com). +an_arbitrary_key: Developed an [IOS application](https://example.com). highlights: - Received more than **100,000 downloads**. - Managed a team of **5** engineers. ``` -By default, the `summary` key will not affect the output as the built-in templates do not use it. However, you can use the `summary` key in your custom templates. Further information on overriding the built-in templates with custom ones can be found [here](index.md#overriding-built-in-themes). +By default, the `an_arbitrary_key` key will not affect the output as the built-in templates do not use it. However, you can use the `an_arbitrary_key` key in your custom templates. Further information on overriding the built-in templates with custom ones can be found [here](index.md#overriding-built-in-themes). + +Also, you can use arbitrary keys in the `cv` field. You can use them anywhere in the templates, but generally, they are used in the header of the CV (`Header.j2.tex`). + +```yaml hl_lines="3" +cv: + name: John Doe + label_as_an_arbitrary_key: Software Engineer +``` ## "`design`" field @@ -295,6 +315,7 @@ Here is an example: ```yaml locale_catalog: phone_number_format: national # (1)! + date_style: "MONTH_ABBREVIATION YEAR" # (2)! abbreviations_for_months: # translation of the month abbreviations - Jan - Feb @@ -330,3 +351,4 @@ locale_catalog: ``` 1. The available phone number formats are: `national`, `international`, and `E164`. +2. The `MONTH_ABBREVIATION` and `YEAR` are placeholders. The available placeholders are: `FULL_MONTH_NAME`, `MONTH_ABBREVIATION`, `MONTH`, `MONTH_IN_TWO_DIGITS`, `YEAR`, and `YEAR_IN_TWO_DIGITS`. \ No newline at end of file