rendercv/docs/user_guide.md

283 lines
8.4 KiB
Markdown
Raw Normal View History

2023-10-20 20:09:19 +00:00
# RenderCV: User Guide
2024-02-23 21:39:36 +00:00
This document provides everything you need to know about the usage of RenderCV.
2024-02-23 17:58:53 +00:00
2024-02-23 21:39:36 +00:00
## Installation
2024-02-23 17:58:53 +00:00
2024-02-23 21:39:36 +00:00
> RenderCV doesn't require a $\LaTeX$ installation; it comes with it!
2024-02-23 17:58:53 +00:00
2024-02-23 21:39:36 +00:00
1. Install [Python](https://www.python.org/downloads/) (3.10 or newer).
2. Run the command below to install RenderCV.
2023-10-20 20:09:19 +00:00
```bash
pip install rendercv
```
2024-02-23 21:39:36 +00:00
or
```bash
python -m pip install rendercv
```
2023-10-20 20:09:19 +00:00
2024-02-23 21:39:36 +00:00
## 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.
2023-10-20 20:09:19 +00:00
```bash
rendercv new "Your Full Name"
```
2024-02-23 21:39:36 +00:00
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.
2023-10-20 20:09:19 +00:00
!!! 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"
2024-02-23 21:39:36 +00:00
1. Ensure your editor of choice has support for JSON Schema.
2023-10-20 20:09:19 +00:00
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
```
2024-02-23 21:39:36 +00:00
## The YAML structure of the input file
RenderCV's input file consists of two parts: `cv` and `design`.
```yaml
cv:
...
2024-02-24 15:38:58 +00:00
YOUR CONTENT
2024-02-23 21:39:36 +00:00
...
design:
...
YOUR DESIGN
...
```
2024-02-24 15:38:58 +00:00
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.
2024-02-23 21:39:36 +00:00
2024-02-24 15:38:58 +00:00
### "`cv`" section of the YAML input
2024-02-23 21:39:36 +00:00
The `cv` section of the YAML input starts with generic information, as shown below:
```yaml
cv:
name: John Doe
2024-02-25 14:16:17 +00:00
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
2024-02-24 15:38:58 +00:00
...
2024-02-23 21:39:36 +00:00
```
None of the values above are required. You can omit any or all of them, and RenderCV will adapt to your input.
2024-03-05 22:20:20 +00:00
The main content of your CV is stored in a field called sections.
2024-02-23 21:39:36 +00:00
```yaml
cv:
name: John Doe
2024-02-25 14:16:17 +00:00
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
2024-02-23 21:39:36 +00:00
sections:
...
YOUR CONTENT
...
2023-10-20 20:09:19 +00:00
```
2024-02-24 15:38:58 +00:00
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.
2024-02-23 21:39:36 +00:00
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
2024-02-24 15:38:58 +00:00
end_date: 2020-01-10
2024-02-23 21:39:36 +00:00
location: TX, USA
highlights:
- This is a highlight (bullet point).
- This is another highlight.
```
2023-10-20 20:09:19 +00:00
2024-02-24 15:38:58 +00:00
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.
2023-10-20 20:09:19 +00:00
2024-02-25 14:16:17 +00:00
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).
2023-10-20 20:09:19 +00:00
2024-02-23 21:39:36 +00:00
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:
2023-10-20 20:09:19 +00:00
2024-02-23 17:58:53 +00:00
{% for entry_name, entry in showcase_entries.items() %}
2024-02-23 21:39:36 +00:00
#### {{ entry_name }}
2023-10-20 20:09:19 +00:00
```yaml
2024-02-23 17:58:53 +00:00
{{ entry["yaml"] }}
2023-10-20 20:09:19 +00:00
```
2024-02-23 17:58:53 +00:00
{% for figure in entry["figures"] %}
`{{ figure["theme"] }}` theme:
![figure["alt_text"]]({{ figure["path"] }})
{% endfor %}
2024-02-23 21:39:36 +00:00
{% endfor %}
2024-02-24 15:38:58 +00:00
### "`design`" section of the YAML input
2024-02-23 21:39:36 +00:00
2024-02-24 15:38:58 +00:00
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).)
2024-02-23 21:39:36 +00:00
```yaml
design:
theme: classic
2024-02-24 15:38:58 +00:00
...
2024-02-23 21:39:36 +00:00
```
2024-02-24 15:38:58 +00:00
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)).
2024-02-23 21:39:36 +00:00
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:
2024-02-24 15:38:58 +00:00
``` { .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
```
2024-02-23 21:39:36 +00:00
2024-02-24 15:38:58 +00:00
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.
2024-02-23 21:39:36 +00:00
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{
2024-02-24 15:38:58 +00:00
((* if design.show_only_years *))
<<entry.date_string_only_years>>
((* else *))
<<entry.date_string>>
((* endif *))
2024-02-23 21:39:36 +00:00
}{
<<entry.position>>
}{
<<entry.company>>
}{
<<entry.location>>
}{}{}
((* for item in entry.highlights *))
\cvline{}{\small <<item>>}
((* endfor *))
```
2024-02-24 15:38:58 +00:00
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/).
2024-02-23 21:39:36 +00:00
### 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.
2024-02-25 14:16:17 +00:00
For example, an `__init__.py` file is shown below:
2024-02-23 21:39:36 +00:00
```python
from typing import Literal
import pydantic
class YourcustomthemeThemeOptions(pydantic.BaseModel):
theme: Literal["yourcustomtheme"]
option1: str
option2: str
option3: int
option4: bool
```
2024-02-25 14:16:17 +00:00
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:
2024-02-23 21:39:36 +00:00
2024-02-24 15:38:58 +00:00
```latex
<<design.option1>>
<<design.option2>>
((* if design.option4 *))
<<design.option3>>
((* endif *))
2024-02-23 21:39:36 +00:00
```