From ef04e054768809014246f0314d0393b5e35aa972 Mon Sep 17 00:00:00 2001 From: Sina Atalay Date: Sun, 19 May 2024 00:02:14 +0300 Subject: [PATCH] docs: improve the user guide --- docs/update_rendercv_files.py | 6 +- docs/user_guide.md | 304 ------------------ docs/user_guide/index.md | 243 ++++++++++++++ .../structure_of_the_yaml_input_file.md | 291 +++++++++++++++++ mkdocs.yaml | 6 +- 5 files changed, 544 insertions(+), 306 deletions(-) delete mode 100644 docs/user_guide.md create mode 100644 docs/user_guide/index.md create mode 100644 docs/user_guide/structure_of_the_yaml_input_file.md diff --git a/docs/update_rendercv_files.py b/docs/update_rendercv_files.py index f276649..f0588d0 100644 --- a/docs/update_rendercv_files.py +++ b/docs/update_rendercv_files.py @@ -151,7 +151,7 @@ def define_env(env): "yaml": dictionary_to_yaml(eval(entry)), "figures": [ { - "path": f"assets/images/{theme}/{entry}.png", + "path": f"../assets/images/{theme}/{entry}.png", "alt_text": f"{proper_entry_name} in {theme}", "theme": theme, } @@ -173,6 +173,10 @@ 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] + env.variables["available_themes"] = ", ".join(themes) + def generate_entry_figures(): """Generate an image for each entry type and theme.""" diff --git a/docs/user_guide.md b/docs/user_guide.md deleted file mode 100644 index 5e417e0..0000000 --- a/docs/user_guide.md +++ /dev/null @@ -1,304 +0,0 @@ -# RenderCV: User Guide - -This document provides everything you need to know about the usage of RenderCV. - -## Installation - -> RenderCV doesn't require a $\LaTeX$ installation; it comes with it! - -1. Install [Python](https://www.python.org/downloads/) (3.10 or newer). - -2. Run the command below to install RenderCV. - -```bash -pip install rendercv -``` - -or - -```bash -python -m pip install rendercv -``` - -## Generating the input file - -To get started, navigate to the directory where you want to create your CV and run the command below to create the input file. - -```bash -rendercv new "Your Full Name" -``` - -or - -```bash -python -m rendercv new "Your Full Name" -``` - -This will create a YAML input file for RenderCV called `Your_Name_CV.yaml`. Open this file in your favorite IDE and start editing. - -!!! tip - - To maximize your productivity while editing the input YAML file, set up RenderCV's JSON Schema in your IDE. It will validate your inputs on the fly and give auto-complete suggestions. - - === "Visual Studio Code" - - 1. Install [YAML language support](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension. - 2. Then the Schema will be automatically set up because the file ends with `_CV.yaml`. - - === "Other" - - 1. Ensure your editor of choice has support for JSON Schema. - 2. Add the following line at the top of `Your_Name_CV.yaml`: - - ``` yaml - # yaml-language-server: $schema=https://github.com/sinaatalay/rendercv/blob/main/schema.json?raw=true - ``` - -## The YAML structure of the input file - -RenderCV's input file consists of two parts: `cv` and `design`. - -```yaml -cv: - ... - YOUR CONTENT - ... -design: - ... - YOUR DESIGN - ... -``` - -The `cv` part contains only the **content of the CV**, and the `design` part contains only the **design options of the CV**. That's how the design and content are separated. - -### "`cv`" section of the YAML input - -The `cv` section of the YAML input starts with generic information, as shown below: - -```yaml -cv: - name: John Doe - location: Your Location - email: youremail@yourdomain.com - phone: tel:+90-541-999-99-99 - website: https://yourwebsite.com/ - social_networks: - - network: LinkedIn - username: yourusername - - network: GitHub - username: yourusername - ... -``` - -None of the values above are required. You can omit any or all of them, and RenderCV will adapt to your input. - -The main content of your CV is stored in a field called sections. - -```yaml -cv: - name: John Doe - location: Your Location - email: youremail@yourdomain.com - phone: tel:+90-541-999-99-99 - website: https://yourwebsite.com/ - social_networks: - - network: LinkedIn - username: yourusername - - network: GitHub - username: yourusername - sections: - ... - YOUR CONTENT - ... -``` - -The `sections` field is a dictionary where the keys are the section titles, and the values are lists. Each item of the list is an entry for that section. - -Here is an example: - -```yaml -cv: - sections: - this_is_a_section_title: - - This is a TextEntry. - - This is another TextEntry under the same section. - - This is another another TextEntry under the same section. - this_is_another_section_title: - - company: This time it's an ExperienceEntry. - position: Your position - start_date: 2019-01-01 - end_date: 2020-01 - location: TX, USA - highlights: - - This is a highlight (bullet point). - - This is another highlight. - - company: Another ExperienceEntry. - position: Your position - start_date: 2019-01-01 - end_date: 2020-01-10 - location: TX, USA - highlights: - - This is a highlight (bullet point). - - This is another highlight. -``` - -There are six different entry types in RenderCV. Different types of entries cannot be mixed under the same section, so for each section, you can only use one type of entry. - -The available entry types are: [`EducationEntry`](#education-entry), [`ExperienceEntry`](#experience-entry), [`PublicationEntry`](#publication-entry), [`NormalEntry`](#normal-entry), [`OneLineEntry`](#one-line-entry), and [`TextEntry`](#text-entry). - -Each entry type is a different object (a dictionary). All of the entry types and their corresponding look in each built-in theme are shown below: - -{% for entry_name, entry in showcase_entries.items() %} -#### {{ entry_name }} -```yaml -{{ entry["yaml"] }} -``` - {% for figure in entry["figures"] %} -`{{ figure["theme"] }}` theme: -![figure["alt_text"]]({{ figure["path"] }}) - {% endfor %} -{% endfor %} - -### "`design`" section of the YAML input - -The `cv` part of the input contains your content, and the `design` part contains your design. The `design` part starts with a theme name. Currently, there are three built-in themes (`classic`, `sb2nov`, and `moderncv`), but custom themes can also be used (see [below](#using-custom-themes).) - -```yaml -design: - theme: classic - ... -``` - -Each theme has different options for design. `classic` and `sb2nov` almost use identical options, but `moderncv` is slightly different. Please use an IDE that supports JSON schema to avoid missing any available options for the theme (see [above](#generating-the-input-file)). - -An example `design` part for a `classic` theme is shown below: - -```yaml -design: - theme: classic - color: rgb(0,79,144) - disable_page_numbering: false - font_size: 10pt - header_font_size: 30 pt - page_numbering_style: NAME - Page PAGE_NUMBER of TOTAL_PAGES - page_size: a4paper - disable_last_updated_date: false - text_alignment: justified - margins: - page: - bottom: 2 cm - left: 1.24 cm - right: 1.24 cm - top: 2 cm - section_title: - bottom: 0.2 cm - top: 0.2 cm - entry_area: - date_and_location_width: 4.1 cm - left_and_right: 0.2 cm - vertical_between: 0.12 cm - highlights_area: - left: 0.4 cm - top: 0.10 cm - vertical_between_bullet_points: 0.10 cm - header: - bottom: 0.2 cm - horizontal_between_connections: 1.5 cm - vertical_between_name_and_connections: 0.2 cm -``` - -## Command-line interface (CLI) - -Currently, RenderCV has two command-line interface functions: `new`, and `render`. - -### `rendercv new` - -`rendercv new YOUR_FULL_NAME` generates a sample YAML input file to get started. An optional `theme` input allows you to generate a YAML file for a specific built-in theme. - -```bash -rendercv new --theme THEME_NAME "John Doe" -``` - -### `rendercv render` - -`rendercv render INPUT_FILE_PATH` renders the given YAML input file. An optional `use-local-latex-command` option can be used to generate the CV with the local LaTeX installation. - -```bash -rendercv render --use-local-latex-command pdflatex John_Doe_CV.yaml -``` - - -## Using custom themes - -RenderCV allows you to move your $\LaTeX$ CV code to RenderCV. To do this, you will need to create some files: - -``` { .sh .no-copy } -├── yourcustomtheme -│ ├── Preamble.j2.tex -│ ├── Header.j2.tex -│ ├── EducationEntry.j2.tex -│ ├── ExperienceEntry.j2.tex -│ ├── NormalEntry.j2.tex -│ ├── OneLineEntry.j2.tex -│ ├── PublicationEntry.j2.tex -│ ├── TextEntry.j2.tex -│ ├── SectionBeginning.j2.tex -│ └── SectionEnding.j2.tex -└── Your_Full_Name_CV.yaml -``` - -Each of these `*.j2.tex` files is $\LaTeX$ code with some Python in it. These files allow RenderCV to create your CV out of the YAML input. - -The best way to understand how they work is to look at the source code of built-in themes. For example, the content of `ExperienceEntry.j2.tex` for the `moderncv` theme is shown below: - -```latex -\cventry{ - ((* if design.show_only_years *)) - <> - ((* else *)) - <> - ((* endif *)) -}{ - <> -}{ - <> -}{ - <> -}{}{} -((* for item in entry.highlights *)) -\cvline{}{\small <>} -((* endfor *)) -``` - -The values between `<<` and `>>` are the names of Python variables, allowing you to write a $\\LaTeX$ CV without writing any content. Those will be replaced with the values found in the YAML input. Also, the values between `((*` and `*))` are Python blocks, allowing you to use loops and conditional statements. - -The process of generating $\\LaTeX$ files like this is called "templating," and it's achieved with a Python package called [Jinja](https://jinja.palletsprojects.com/en/3.1.x/). - -### Creating custom theme options - -If you want to have some `design` options under your YAML input file's `design` section for your custom theme, you can create a `__init__.py` file inside your theme directory. - -For example, an `__init__.py` file is shown below: - -```python -from typing import Literal - -import pydantic - -class YourcustomthemeThemeOptions(pydantic.BaseModel): - theme: Literal["yourcustomtheme"] - option1: str - option2: str - option3: int - option4: bool -``` - -Then, RenderCV will parse your custom design options from the YAML input, and you can use these variables inside your `*.j2.tex` files as shown below: - -```latex -<> -<> -((* if design.option4 *)) - <> -((* endif *)) -``` \ No newline at end of file diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md new file mode 100644 index 0000000..c6ba3ac --- /dev/null +++ b/docs/user_guide/index.md @@ -0,0 +1,243 @@ +# RenderCV: User Guide + +This document provides everything you need to know about the usage of RenderCV. + +## Installation + +> RenderCV doesn't require a $\LaTeX$ installation; it comes with it! + +1. Install [Python](https://www.python.org/downloads/) (3.10 or newer). + +2. Run the command below to install RenderCV. + +```bash +pip install rendercv +``` + +## Getting started with the `new` command + +To get started, navigate to the directory where you want to create your CV and run the command below to create the input files. + +```bash +rendercv new "Your Full Name" +``` +This command will create the following files: + +- A YAML input file called `Your_Name_CV.yaml`. + + This file will contain all the content and design options of your CV. + +- A directory called `classic`, which contains the LaTeX source code of the default built-in theme, "classic". + + This directory contains the LaTeX source code of RenderCV's default built-in theme, `classic`. You can update its contents to tweak the appearance of the output PDF file. + +- A directory called `markdown`, which contains the Markdown source code the CV. + + This directory contains the Markdown source code of RenderCV's default Markdown template. You can update its contents to tweak the Markdown output of the CV. + +### Options of the `new` command + +The `new` command has some options: + +- `#!bash --theme "THEME_NAME"`: Generates files for a specific built-in theme, instead of the default `classic` theme. Currently, the available themes are: {{available_themes}}. +```bash +rendercv new "Your Full Name" --theme "THEME_NAME" +``` + +- `#!bash --dont-create-theme-source-files`: Prevents the creation of the theme source files. By default, the theme source files are created. +```bash +rendercv new "Your Full Name" --dont-create-theme-source-files +``` + +- `#!bash --dont-create-markdown-source-files`: Prevents the creation of the Markdown source files. By default, the Markdown source files are created. +```bash +rendercv new "Your Full Name" --dont-create-markdown-source-files +``` + +## Structure of the YAML input file + +The YAML input file contains all the content and design options of your CV. A detailed explanation of the structure of the YAML input file is provided [here](input_file_structure.md). + + +## Rendering the CV with the `render` command + +To render a YAML input file, run the command below. + +```bash +rendercv render "Your_Name_CV.yaml" +``` + +This command will generate a directory called `rendercv_output`, which contains the following files: + +- The CV in PDF format, `Your_Name_CV.pdf`. +- LaTeX source code of the PDF file, `Your_Name_CV.tex`. +- PNG files for each page of the PDF file. +- The CV in Markdown format, `Your_Name_CV.md`. +- An HTML file from the Markdown file, `Your_Name_CV_PASTETOGRAMMARLY.html`. + + This file is generated so that it can be opened in a browser and pasted into Grammarly or similar tools for spell and grammar checking. + +- Some log and auxiliary files related to the LaTeX compilation process. + +If the theme and Markdown source files are found in the directory, they will override the default built-in theme and Markdown template. You don't need to provide all the source files; you can just provide the ones you want to override. + +### Options of the `render` command + +The `render` command has some options: + +- `#!bash --use-local-latex-command "LATEX_COMMAND"`: Generates the CV with the local LaTeX installation, i.e., runs `LATEX_COMMAND`. By default, RenderCV uses its own TinyTeX distribution. +```bash +rendercv render "Your_Name_CV.yaml" --use-local-latex-command "pdflatex" +``` +- `#!bash --output-folder-name "OUTPUT_FOLDER_NAME"`: Generates the output files in a folder with the given name. By default, the output folder name is `rendercv_output`. The output folder will be created in the current working directory. +```bash +rendercv render "Your_Name_CV.yaml" --output-folder-name "OUTPUT_FOLDER_NAME" +``` + +- `#!bash --latex-path LATEX_PATH`: Copies the generated LaTeX source code from the output folder and pastes it to the specified path. +```bash +rendercv render "Your_Name_CV.yaml" --latex-path "PATH" +``` + +- `#!bash --pdf-path PDF_PATH`: Copies the generated PDF file from the output folder and pastes it to the specified path. +```bash +rendercv render "Your_Name_CV.yaml" --pdf-path "PATH" +``` + +- `#!bash --markdown-path MARKDOWN_PATH`: Copies the generated Markdown file from the output folder and pastes it to the specified path. +```bash +rendercv render "Your_Name_CV.yaml" --markdown-path "PATH" +``` + +- `#!bash --html-path HTML_PATH`: Copies the generated HTML file from the output folder and pastes it to the specified path. +```bash +rendercv render "Your_Name_CV.yaml" --html-path "PATH" +``` + +- `#!bash --png-path PNG_PATH`: Copies the generated PNG files from the output folder and pastes them to the specified path. +```bash +rendercv render "Your_Name_CV.yaml" --png-path "PATH" +``` + +- `#!bash --dont-generate-markdown`: Prevents the generation of the Markdown file. +```bash +rendercv render "Your_Name_CV.yaml" --dont-generate-markdown +``` + +- `#!bash --dont-generate-html`: Prevents the generation of the HTML file. +```bash +rendercv render "Your_Name_CV.yaml" --dont-generate-html +``` + +- `#!bash --dont-generate-png`: Prevents the generation of the PNG files. +```bash +rendercv render "Your_Name_CV.yaml" --dont-generate-png +``` + +- `#!bash --ANY.LOCATION.IN.THE.YAML.FILE "VALUE"`: Overrides the value of `ANY.LOCATION.IN.THE.YAML.FILE` with `VALUE`. This option can be used to avoid storing sensitive information in the YAML file. Sensitive information, like phone numbers, can be passed as a command-line argument with environment variables. This method is also beneficial for creating multiple CVs using the same YAML file by changing only a few values. Here are a few examples: +```bash +rendercv render "Your_Name_CV.yaml" --cv.phone "+905555555555" +``` +```bash +rendercv render "Your_Name_CV.yaml" --cv.sections.education.1.institution "Your University" +``` + + Multiple `#!bash --ANY.LOCATION.IN.THE.YAML.FILE "VALUE"` options can be used in the same command. + +## Creating custom themes with the `create-theme` command + +RenderCV is a general LaTeX CV framework. It allows you to use any LaTeX code to generate your CVs. To begin developing a custom theme, run the command below. + +```bash +rendercv create-theme "mycustomtheme" +``` + +This command will create a directory called `mycustomtheme`, which contains the following files: + +``` { .sh .no-copy } +├── mycustomtheme +│ ├── __init__.py +│ ├── Preamble.j2.tex +│ ├── Header.j2.tex +│ ├── EducationEntry.j2.tex +│ ├── ExperienceEntry.j2.tex +│ ├── NormalEntry.j2.tex +│ ├── OneLineEntry.j2.tex +│ ├── PublicationEntry.j2.tex +│ ├── TextEntry.j2.tex +│ ├── SectionBeginning.j2.tex +│ └── SectionEnding.j2.tex +└── Your_Full_Name_CV.yaml +``` + +The files are copied from the `classic` theme. You can update the contents of these files to create your custom theme. + +Each of these `*.j2.tex` files is $\LaTeX$ code with some Python in it. These files allow RenderCV to create your CV out of the YAML input. + +The best way to understand how they work is to look at the source code of built-in themes: + +- [`classic` templates](../reference/themes/classic.md) +- [`engineeringresumes` templates](../reference/themes/engineeringresumes.md) +- [`sb2nov` templates](../reference/themes/sb2nov.md) +- [`moderncv` templates](../reference/themes/moderncv.md) + +For example, the content of `ExperienceEntry.j2.tex` for the `moderncv` theme is shown below: + +```latex +\cventry{ + ((* if design.show_only_years *)) + <> + ((* else *)) + <> + ((* endif *)) +}{ + <> +}{ + <> +}{ + <> +}{}{} +((* for item in entry.highlights *)) +\cvline{}{\small <>} +((* endfor *)) +``` + +The values between `<<` and `>>` are the names of Python variables, allowing you to write a $\\LaTeX$ CV without writing any content. Those will be replaced with the values found in the YAML input. Also, the values between `((*` and `*))` are Python blocks, allowing you to use loops and conditional statements. + +The process of generating $\\LaTeX$ files like this is called "templating," and it's achieved with a Python package called [Jinja](https://jinja.palletsprojects.com/en/3.1.x/). + +Also, the `__init__.py` file found in the theme directory is used to define the design options of the custom theme. You can define your custom design options in this file. + +For example, an `__init__.py` file is shown below: + +```python +from typing import Literal + +import pydantic + +class YourcustomthemeThemeOptions(pydantic.BaseModel): + theme: Literal["yourcustomtheme"] + option1: str + option2: str + option3: int + option4: bool +``` + +Then, RenderCV will parse your custom design options from the YAML input, and you can use these variables inside your `*.j2.tex` files as shown below: + +```latex +<> +<> +((* if design.option4 *)) + <> +((* endif *)) +``` + +### Options of the `create-theme` command + +The `create-theme` command has some options: + +- `#!bash --based-on "THEME_NAME"`: Generates a custom theme based on the specified built-in theme, instead of the default `classic` theme. Currently, the available themes are: {{available_themes}}. +```bash +rendercv create-theme "mycustomtheme" --based-on "THEME_NAME" +``` diff --git a/docs/user_guide/structure_of_the_yaml_input_file.md b/docs/user_guide/structure_of_the_yaml_input_file.md new file mode 100644 index 0000000..fcb71bf --- /dev/null +++ b/docs/user_guide/structure_of_the_yaml_input_file.md @@ -0,0 +1,291 @@ +# Structure of the YAML Input File + +RenderCV's input file consists of three parts: `cv`, `design`, and `locale_catalog`. + +```yaml title="Your_Name_CV.yaml" +cv: + ... + YOUR CONTENT + ... +design: + ... + YOUR DESIGN + ... +locale_catalog: + ... + TRANSLATIONS TO YOUR LANGUAGE + ... +``` + +- The `cv` section is mandatory. It contains the **content of the CV**. +- The `design` section is optional. It contains the **design options of the CV**. If you don't provide a `design` section, RenderCV will use the default design options with the `classic` theme. +- The `locale_catalog` section is optional. You can provide translations for some of the strings used in the CV, for example, month abbreviations. RenderCV will use English strings if you don't provide a `locale_catalog` section. + +!!! tip + To maximize your productivity while editing the input YAML file, set up RenderCV's JSON Schema in your IDE. It will validate your inputs on the fly and give auto-complete suggestions. + + === "Visual Studio Code" + + 1. Install [YAML language support](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension. + 2. Then the Schema will be automatically set up because the file ends with `_CV.yaml`. + 3. Press `Ctrl + Space` to see the auto-complete suggestions. + + === "Other" + + 1. Ensure your editor of choice has support for JSON Schema. + 2. Add the following line at the top of `Your_Name_CV.yaml`: + + ``` yaml + # yaml-language-server: $schema=https://github.com/sinaatalay/rendercv/blob/main/schema.json?raw=true + ``` + 3. Press `Ctrl + Space` to see the auto-complete suggestions. + +## "`cv`" section of the YAML input + +The `cv` section of the YAML input starts with generic information, as shown below. + +```yaml +cv: + name: John Doe + label: Mechanical Engineer + location: Your Location + email: youremail@yourdomain.com + phone: +905419999999 + website: https://example.com/ + social_networks: + - network: LinkedIn + username: yourusername + - network: GitHub + username: yourusername + ... +``` + +None of the values above are required. You can omit any or all of them, and RenderCV will adapt to your input. These generic fields are used in the header of the CV. + +The main content of your CV is stored in a field called `sections`. + +```yaml hl_lines="12 13 14 15" +cv: + name: John Doe + location: Your Location + email: youremail@yourdomain.com + phone: tel:+90-541-999-99-99 + website: https://yourwebsite.com/ + social_networks: + - network: LinkedIn + username: yourusername + - network: GitHub + username: yourusername + sections: + ... + YOUR CONTENT + ... +``` + +The `sections` field is a dictionary where the keys are the section titles, and the values are lists. Each item of the list is an entry for that section. + +Here is an example: + +```yaml +cv: + sections: + this_is_a_section_title: + - This is a TextEntry. + - This is another TextEntry under the same section. + - This is another another TextEntry under the same section. + this_is_another_section_title: + - company: This time it's an ExperienceEntry. + position: Your position + start_date: 2019-01-01 + end_date: 2020-01 + location: TX, USA + highlights: + - This is a highlight (bullet point). + - This is another highlight. + - company: Another ExperienceEntry. + position: Your position + start_date: 2019-01-01 + end_date: 2020-01-10 + location: TX, USA + highlights: + - This is a highlight (bullet point). + - This is another highlight. +``` + +There are seven different entry types in RenderCV. Different types of entries cannot be mixed under the same section, so for each section, you can only use one type of entry. + +The available entry types are: [`EducationEntry`](#education-entry), [`ExperienceEntry`](#experience-entry), [`PublicationEntry`](#publication-entry), [`NormalEntry`](#normal-entry), [`OneLineEntry`](#one-line-entry), [`BulletEntry`](#bullet-entry) and [`TextEntry`](#text-entry). + +Each entry type is a different object (a dictionary). Below, you can find all the entry types along with their optional/mandatory fields and how they appear in each built-in theme. + +{% for entry_name, entry in showcase_entries.items() %} +### {{ entry_name }} + +{% if entry_name == "Education Entry" %} + +**Mandatory Fields:** + +- `institution`: The name of the institution. +- `area`: The area of study. + +**Optional Fields:** + +- `degree`: The type of degree. +- `location`: The location. +- `start_date`: The start date in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format. +- `end_date`: The end date in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format or "present". +- `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" %} + +**Mandatory Fields:** + +- `company`: The name of the company. +- `position`: Your position. + +**Optional Fields:** + +- `location`: The location. +- `start_date`: The start date in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format. +- `end_date`: The end date in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format or "present". +- `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" %} + +**Mandatory Fields:** + +- `title`: The title of the publication. +- `authors`: The authors of the publication. + +**Optional Fields:** + +- `doi`: The DOI of the publication. +- `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" %} + +**Mandatory Fields:** + +- `name`: The name of the entry. + +**Optional Fields:** + +- `location`: The location. +- `start_date`: The start date in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format. +- `end_date`: The end date in `YYYY-MM-DD`, `YYYY-MM`, or `YYYY` format or "present". +- `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 == "OneLineEntry" %} + +**Mandatory Fields:** + +- `label`: The label of the entry. +- `details`: The value of the entry. + +{% elif entry_name == "Bullet Entry" %} + +**Mandatory Fields:** + +- `bullet`: The bullet point. + +{% elif entry_name == "Text Entry" %} + +**Mandatory Fields:** + +- The text itself. + +{% endif %} + +```yaml +{{ entry["yaml"] }} +``` + {% for figure in entry["figures"] %} +`{{ figure["theme"] }}` theme: +![figure["alt_text"]]({{ figure["path"] }}) + {% endfor %} +{% endfor %} + +## "`design`" section of the YAML input + +The `cv` part of the input contains your content, and the `design` part contains your design options. The `design` part starts with a theme name. Currently, the available themes are: {{available_themes}}. However, custom themes can also be used (see [here](index.md#creating-custom-themes-with-the-create-theme-command).) + +```yaml +design: + theme: classic + ... +``` + +Each theme may have different options for design. `classic`, `sb2nov`, and `engineeringresumes` almost use identical options, but `moderncv` is slightly different. Please use an IDE that supports JSON schema to avoid missing any available options for the theme (see [above](#structure-of-the-yaml-input-file)). + +An example `design` part for a `classic` theme is shown below: + +```yaml +design: + theme: classic + color: blue + disable_external_link_icons: false + disable_last_updated_date: false + last_updated_date_style: Last updated in TODAY + disable_page_numbering: false + page_numbering_style: NAME - Page PAGE_NUMBER of TOTAL_PAGES + font: Source Sans 3 + font_size: 10pt + header_font_size: "30 pt" + page_size: a4paper + show_timespan_in: + - 'Experience' + text_alignment: justified + margins: + page: + bottom: 2 cm + left: 2 cm + right: 2 cm + top: 2 cm + section_title: + bottom: 0.2 cm + top: 0.3 cm + entry_area: + date_and_location_width: 4.5 cm + education_degree_width: 1 cm + left_and_right: 0.2 cm + vertical_between: 0.2 cm + highlights_area: + left: 0.4 cm + top: 0.10 cm + vertical_between_bullet_points: 0.10 cm + header: + bottom: 0.3 cm + horizontal_between_connections: 0.5 cm + vertical_between_name_and_connections: 0.3 cm +``` + +## "`locale_catalog`" section of the YAML input + +This section is what makes RenderCV a multilingual tool. RenderCV uses some English strings to render PDFs. For example, it takes the dates in ISO format (`2020-01-01`) and converts them into human-friendly strings (`"Jan. 2020"`). However, you can override these strings for your own language or needs with the `locale_catalog` section. + +Here is an example: + +```yaml +locale_catalog: + abbreviations_for_months: + - Jan + - Feb + - Mar + - Apr + - May + - Jun + - Jul + - Aug + - Sep + - Oct + - Nov + - Dec + month: "month" + months: "months" + year: "year" + years: "years" + present: "present" + to: "to" +``` \ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml index 7c544b6..3942631 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -43,10 +43,14 @@ theme: - search.highlight # highlight search results after going to a page - search.suggest # show search suggestions while typing - toc.follow # if toc sidebar doesn't fit, scroll to the active heading + - content.code.annotate # allow annotations in code blocks nav: - Overview: index.md - - User Guide: user_guide.md + - User Guide: + - User Guide: user_guide/index.md + - Structure of the YAML input file: user_guide/structure_of_the_yaml_input_file.md + - Developer Guide: developer_guide.md - Reference: - Reference: reference/index.md - cli.py: reference/cli.md