From 31cac973ee12c1106534cc7714d1349439478d83 Mon Sep 17 00:00:00 2001 From: Sina Atalay Date: Fri, 23 Feb 2024 22:39:36 +0100 Subject: [PATCH] update user guide --- docs/user_guide.md | 219 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 201 insertions(+), 18 deletions(-) diff --git a/docs/user_guide.md b/docs/user_guide.md index 579746a..2df9124 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,23 +1,40 @@ # 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! -After you've installed RenderCV with +1. Install [Python](https://www.python.org/downloads/) (3.10 or newer). + +2. Run the command below to install RenderCV. ```bash pip install rendercv ``` -you can start rendering your CV. +or -Firstly, go to the directory where you want your CV files located and run: +```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" ``` -This will create a YAML input file for RenderCV called `Your_Name_CV.yaml`. Open this generated file in your favorite IDE and start editing. It governs all the features of RenderCV. +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 @@ -30,32 +47,100 @@ This will create a YAML input file for RenderCV called `Your_Name_CV.yaml`. Open === "Other" - 1. Ensure your editor of choice has support for YAML schema validation. + 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 ``` -After you're done editing your input file, run the command below to render your CV: -```bash -rendercv render Your_Name_CV.yaml +## 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 + ... ``` -## Entry Types +The `cv` part contains only the content of the CV, and the `design` part contains only the design properties of the CV. That's how the design and content are separated. -There are five entry types in RenderCV: +### `cv` section of the YAML input -1. *EducationEntry* -2. *ExperienceEntry* -3. *NormalEntry* -4. *OneLineEntry* -5. *PublicationEntry* +The `cv` section of the YAML input starts with generic information, as shown below: -The whole CV consists of these entries. +```yaml +cv: + name: John Doe + email: johndoe@example.com + phone: "+905555555555" + website: https://example.com + label: Mechanical Engineer + location: Istanbul, Türkiye +``` + +None of the values above are required. You can omit any or all of them, and RenderCV will adapt to your input. + +The real content of your CV is stored in a field called sections. + +```yaml +cv: + name: John Doe + email: johndoe@example.com + phone: "+905555555555" + website: https://example.com + label: Mechanical Engineer + location: Istanbul, Türkiye + sections: + ... + YOUR CONTENT + ... +``` + +The `sections` field is a dictionary where the keys are the section titles, and the values are lists. Each item on the list is an entry in the CV. + +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 + location: TX, USA + highlights: + - This is a highlight (bullet point). + - This is another highlight. +``` + +There are six different entry types in RenderCV. You must choose one for each section and cannot mix types within a section. + +The available entry types are: `EducationEntry`, `ExperienceEntry`, `PublicationEntry`, `NormalEntry`, `OneLineEntry`, and `TextEntry`. + +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 }} +#### {{ entry_name }} ```yaml {{ entry["yaml"] }} ``` @@ -63,4 +148,102 @@ The whole CV consists of these entries. `{{ figure["theme"] }}` theme: ![figure["alt_text"]]({{ figure["path"] }}) {% endfor %} -{% endfor %} \ No newline at end of file +{% 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 the name of the theme. Currently, there are three built-in themes (`classic`, `sb2nov`, and `moderncv`), but custom themes can also be used (see below.) + +```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). + +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 + show_last_updated_date: true + 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 +``` + +## Using custom themes + +RenderCV allows you to move your $\LaTeX$ CV code to RenderCV. To do this, you will need to create some files: + +BURAYA FOLDER STRUCTURE GOSTERE, INPUT FILE I DA BELIRTEREK, YOUR_THEME SEKLINDE BIR DIRECTORY ALTINDA ZORUNLU TUM DOSYALARI GOSTER. + +Each of these 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, the `moderncv` theme's `__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, and you can use these variables inside your `*.j2.tex` as shown below: + +``` +``` \ No newline at end of file