eyhc
/
rendercv
mirror of https://github.com/eyhc1/rendercv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: update

This commit is contained in:
Sina Atalay 2024-06-17 21:57:50 +03:00
parent 031687f5ab
commit 75169637c3
19 changed files with 329 additions and 306 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@ -11,15 +11,15 @@
</div>
RenderCV is a $\LaTeX$ CV/resume framework. It allows you to create a high-quality CV as a PDF from a YAML file with full Markdown syntax support and complete control over the $\LaTeX$ code.
RenderCV allows you to create a high-quality CV as a PDF from a YAML input file. It supports full Markdown syntax and gives you complete control over the $\LaTeX$ code.
The primary motivation behind the RenderCV is to provide people with a concrete framework that will allow
The primary motivation behind the RenderCV is to provide people with a concrete framework that allows
- Version controlling a CV's content and design separately in an organized manner.
- Building an automated pipeline that can generate the CV as PDF, markdown, and PNG files.
- Version controlling a CV's content and design separately and in an organized manner.
- Building an automated pipeline that updates the final output (PDF, $\LaTeX$, Markdown, HTML, and PNGs) whenever the content is modified.
- Making the CV's design uniform and nicely structured without room for human errors.
RenderCV offers built-in $\LaTeX$ and Markdown templates ready to produce high-quality CVs. However, the templates are entirely arbitrary and can easily be updated to leverage RenderCV's capabilities with your custom CV themes.
RenderCV offers built-in $\LaTeX$ and Markdown templates ready to produce high-quality CVs. However, the templates are entirely arbitrary and can easily be updated to leverage RenderCV's capabilities with custom CV themes.
RenderCV takes a YAML file that looks like this:
@ -51,7 +51,7 @@ cv:
...
```
Then, it produces one of these PDFs with its corresponding $\LaTeX$ code, markdown file, and images as PNGs. Each of these is an example of one of four built-in themes of RenderCV. Click on images to preview PDFs.
Then, it produces one of these PDFs with its corresponding $\LaTeX$ code, Markdown file, HTML file, and images as PNGs. Each of these is an example of one of 4 built-in themes of RenderCV. Click on the images below to preview PDF files.
| [![Classic Theme Example of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/classic.png)](https://github.com/sinaatalay/rendercv/blob/main/examples/John_Doe_ClassicTheme_CV.pdf) | [![Sb2nov Theme Example of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/sb2nov.png)](https://github.com/sinaatalay/rendercv/blob/main/examples/John_Doe_Sb2novTheme_CV.pdf) |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -59,7 +59,7 @@ Then, it produces one of these PDFs with its corresponding $\LaTeX$ code, markdo
It also generates an HTML file so all the content can be pasted into Grammarly or any word processor for spelling and grammar checking.
The contents of the HTML file can be pasted into Grammarly or any word processor for spelling and grammar checking.
![Grammarly for RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/grammarly.gif)
@ -69,7 +69,7 @@ It also validates the input file, and if there are any problems, it tells users
![CLI of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/cli.gif)
RenderCV comes with a JSON Schema so that the input YAML file can be filled out interactively.
RenderCV comes with a JSON Schema so that the YAML input file can be filled out interactively.
![JSON Schema of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/schema.gif)
@ -78,8 +78,6 @@ RenderCV comes with a JSON Schema so that the input YAML file can be filled out
Either use [rendercv-pipeline](https://github.com/sinaatalay/rendercv-pipeline) or follow the steps below.
> 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 in a terminal to install RenderCV.
```bash
@ -89,13 +87,13 @@ Either use [rendercv-pipeline](https://github.com/sinaatalay/rendercv-pipeline)
```bash
rendercv new "Full Name"
```
4. Edit the contents of `Full_Name_CV.yaml` in your favorite editor (*tip: use an editor that supports JSON Schemas*). The templates can be modified as well.
4. Edit the contents of `Full_Name_CV.yaml` in your favorite editor (*tip: use an editor that supports JSON Schemas*).
5. Run the command below to generate your CV.
```bash
rendercv render Full_Name_CV.yaml
```
[Here](https://docs.rendercv.com/user_guide/), you can find a comprehensive user guide that covers the data model (YAML structure) and command-line interface (CLI) in greater detail.
[Here](https://docs.rendercv.com/user_guide/), you can find a comprehensive user guide that covers the structure of the YAML input file and command-line interface (CLI) in greater detail.
## Motivation
@ -103,11 +101,11 @@ Writing the content of a CV and designing a CV are separate issues that should b
RenderCV also provides a general set of utilities that will automate most of the manual work involved in the CV updating process. After updating a single sentence or a date in the YAML input file written in pure English, RenderCV will
- re-create your $\LaTeX$ file.
- render a new PDF file.
- create a new Markdown file.
- create a new HTML document to be pasted into word processors for spelling and grammar checking.
- create PNG files for each page.
- re-create your $\LaTeX$ file,
- render a new PDF file,
- create a new Markdown file,
- create a new HTML document, and
- create images of each page of the PDF file as PNGs.
> Why should I bother using RenderCV instead of $\LaTeX$? I can version-control $\LaTeX$ code too!
@ -116,15 +114,13 @@ RenderCV is not a replacement for $\LaTeX$, but it's a general set of utilities
Here are some advantages of RenderCV over using pure $\LaTeX$:
- RenderCV will separate the content of your CV from your $\LaTeX$ code. They will sit in independent files, and RenderCV will use both to generate your CV.
- You will be able to version-control your design and content separately.
- You will be able to version-control your $\LaTeX$ code and content separately.
- Updating your content in a YAML file is easier than updating a complex $\LaTeX$ file.
- A pure $\LaTeX$ CV will have many code duplications because a CV is a document with a list of sections that contain a list of entries. RenderCV has only one $\LaTeX$ code for each entry type, duplicated automatically based on the YAML input file.
- Spell-checking is not very straightforward in $\LaTeX$ documents.
## Documentation
The source code of RenderCV is well-commented and documented. Reading the source code might be fun as the software structure is explained with docstrings and comments.
The detailed user guide can be found [here](https://docs.rendercv.com/user_guide).
The developer guide can be found [here](https://docs.rendercv.com/developer_guide).
@ -135,10 +131,6 @@ The changelog can be found [here](https://docs.rendercv.com/changelog).
## Contributing
All contributions to RenderCV are welcome! For development, you will need to clone the repository recursively, as TinyTeX is being used as a submodule:
All contributions to RenderCV are welcome! To get started, please read [the developer guide](https://docs.rendercv.com/developer_guide).
```bash
git clone --recursive https://github.com/sinaatalay/rendercv.git
```
All code and development tool specifications are in `pyproject.toml`. Also, don't forget to read [the developer guide](https://docs.rendercv.com/developer_guide).
The source code is thoroughly documented and well-commented, making it an enjoyable read and easy to understand.

12
docs/changelog.md
View File

@ -7,7 +7,7 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
[Click here to see the unreleased changes.](https://github.com/sinaatalay/rendercv/compare/v1.11...HEAD)
[Click here to see the unreleased changes.](https://github.com/sinaatalay/rendercv/compare/v1.10...HEAD)
<!--
### Added
@ -17,7 +17,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
Orcid to ORCID
-->
## [1.11] - 2024-06-01
<!-- ## [1.11] - 2024-06-01
> **Full Changelog**: [v1.10...v1.11]
@ -31,7 +31,7 @@ Orcid to ORCID
### Fixed
- The error related to the `validation_error_cause` flag of Pydantic has been fixed ([#66](https://github.com/sinaatalay/rendercv/issues/66)).
- `rendercv render` with relative input file paths has been fixed ([#95](https://github.com/sinaatalay/rendercv/issues/95)).
- `rendercv render` with relative input file paths has been fixed ([#95](https://github.com/sinaatalay/rendercv/issues/95)). -->
## [1.10] - 2024-05-25
@ -54,7 +54,7 @@ Orcid to ORCID
### Added
- RenderCV is now a multilingual tool. English strings can be overridden with `locale_catalog` section in the YAML input file ([#26](https://github.com/sinaatalay/rendercv/issues/26), [#20](https://github.com/sinaatalay/rendercv/pull/20)). See the [documentation](https://docs.rendercv.com/user_guide/structure_of_the_yaml_input_file/#locale_catalog-section-of-the-yaml-input) for more information.
- PNG files for each page can be generated now ([#57](https://github.com/sinaatalay/rendercv/issues/57)).
- `rendercv new` command now generates Markdown and LaTeX source files in addition to the YAML input file so that the default templates can be modified easily.
- `rendercv new` command now generates Markdown and $\LaTeX$ source files in addition to the YAML input file so that the default templates can be modified easily.
- A new CLI command has been added, `rendercv create-theme`, to allow users to create their own themes easily.
```bash
rendercv create-theme "customtheme" --based-on "classic"
@ -82,7 +82,7 @@ Orcid to ORCID
### Fixed
- `ExperienceEntry` and `NormalEntry` without location and dates have been fixed in the `engineeringresumes`, `classic`, and `sb2nov` themes.
- LaTeX templates have been polished.
- $\LaTeX$ templates have been polished.
- Bugs related to the special characters in email addresses have been fixed ([#64](https://github.com/sinaatalay/rendercv/issues/64)).
## [1.8] - 2024-04-16
@ -194,7 +194,7 @@ Orcid to ORCID
- Markdown `TextEntry`, where all the paragraphs were concatenated into a single paragraph, has been fixed.
- Markdown `OneLineEntry`, where all the one-line entries were concatenated into a single line, has been fixed.
- The `classic` theme's `PublicationEntry`, where blank parentheses were rendered when the `journal` field was not provided, has been fixed.
- A bug, where an email with special characters caused a LaTeX error, has been fixed.
- A bug, where an email with special characters caused a $\LaTeX$ error, has been fixed.
- Unicode error, when `rendercv new` is called with a name with special characters, has been fixed.

110
docs/developer_guide.md
View File

@ -1,110 +0,0 @@
# Developer Guide
This document provides everything you need to know about the development of RenderCV.
## Getting Started
1. Ensure that you have Python version 3.10 or higher.
2. Then, clone the repository recursively (because TinyTeX is being used as a submodule) with the following command.
```bash
git clone --recursive https://github.com/sinaatalay/rendercv.git
```
3. Go to the `rendercv` directory.
```bash
cd rendercv
```
4. Create a virtual environment.
```bash
python -m venv .venv
```
5. Activate the virtual environment.
=== "Windows (PowerShell)"
```powershell
.venv\Scripts\Activate.ps1
```
=== "MacOS/Linux"
```bash
source .venv/bin/activate
```
6. Install the dependencies.
```bash
pip install --editable .[docs,tests,dev]
```
## How RenderCV works?
The flowchart below illustrates the general operations of RenderCV. A detailed documentation of the source code is available in the [reference](reference/index.md).
```mermaid
flowchart TD
A[YAML Input File] --parsing with ruamel.yaml package--> B(Python Dictionary)
B --validation with pydantic package--> C((Pydantic Object))
C --> D[LaTeX File]
C --> E[Markdown File]
E --markdown package--> K[HTML FIle]
D --TinyTeX--> L[PDF File]
L --PyMuPDF package--> Z[PNG Files]
AA[(Jinja2 Templates)] --> D
AA[(Jinja2 Templates)] --> E
```
## Writing Documentation
The documentation's source files are located in the `docs` directory and it is built using the `mkdocs` package. To work on the documentation and see the changes in real-time, run the following command.
```bash
mkdocs serve
```
### Updating the examples and the JSON Schema
The example entry images found in the [Structure of the YAML input file](user_guide/structure_of_the_yaml_input_file.md), the `examples` folder, and the JSON Schema `schema.json` are generated using the script `docs/update_rendercv_files.py`. To update these files, run `update_rendercv_files.py` with the following command.
```bash
python docs/update_rendercv_files.py
```
## Testing
After updating the code, all tests should pass. To run the tests, use the following command.
```bash
pytest
```
### A note about `testdata` folder
In some of the tests:
- RenderCV generates an output with a sample input.
- Then, the output is compared with a reference output, which has been manually generated and stored in `testdata`. If the files differ, the tests fail.
When the `testdata` folder needs to be updated, it can be manually regenerated by setting `update_testdata` to `True` in `conftest.py` and running the tests.
Whenever the `testdata` folder is generated, the files should be reviewed manually to ensure everything works as expected.
## Frequently Asked Questions (FAQ)
### How can I add a new social network to RenderCV?
To add a new social network to RenderCV, go to the `rendercv/data_models.py` file and follow these steps:
1. Append the social network name (for example, "Facebook") to the `SocialNetworkName` type.
2. If necessary, implement its username validation in the `SocialNetwork.check_username` method.
3. Implement its URL generation using the `SocialNetwork.url` method. If the URL can be generated by appending the username to a hostname, only update `url_dictionary`.
4. Finally, include the $\LaTeX$ icon of the social network to the `icon_dictionary` in the `CurriculumVitae.connections` method. RenderCV uses the [`fontawesome5`](https://ctan.org/pkg/fontawesome5?lang=en) package. The available icons can be seen [here](https://fosszone.csd.auth.gr/CTAN/fonts/fontawesome5/doc/fontawesome5.pdf).
Then, the tests should be implemented for the new social network with the following steps:
1. Go to `tests/test_data_models.py` and update `test_social_network_url` accordingly.
2. Go to `tests/conftest.py` and add the new social network to `rendercv_filled_curriculum_vitae_data_model`.
3. Set `update_testdata` to `True` in `conftest.py` and run the tests to update the `testdata` folder.
4. Review the updated `testdata` folder manually to ensure everything works as expected. Then, set `update_testdata` to `False` and push the changes.

18
docs/developer_guide/faq.md Normal file
View File

@ -0,0 +1,18 @@
# Frequently Asked Questions (FAQ)
## How can I add a new social network to RenderCV?
To add a new social network to RenderCV, go to the `rendercv/data_models.py` file and follow these steps:
1. Append the social network name (for example, "Facebook") to the `SocialNetworkName` type.
2. If necessary, implement its username validation in the `SocialNetwork.check_username` method.
3. Implement its URL generation using the `SocialNetwork.url` method. If the URL can be generated by appending the username to a hostname, only update `url_dictionary`.
4. Finally, include the $\LaTeX$ icon of the social network to the `icon_dictionary` in the `CurriculumVitae.connections` method. RenderCV uses the [`fontawesome5`](https://ctan.org/pkg/fontawesome5?lang=en) package. The available icons can be seen [here](https://fosszone.csd.auth.gr/CTAN/fonts/fontawesome5/doc/fontawesome5.pdf).
Then, the tests should be implemented for the new social network with the following steps:
1. Go to `tests/test_data_models.py` and update `test_social_network_url` accordingly, i.e., add a new `(network, username, expected_url)` tuple to the `pytest.mark.parametrize` decorator.
2. Go to `tests/conftest.py` and add the new social network to `rendercv_filled_curriculum_vitae_data_model`.
3. Set `update_testdata` to `True` in `conftest.py` and run the tests to update the `testdata` folder.
4. Review the updated `testdata` folder manually to ensure everything works as expected. Then, set `update_testdata` to `False` and push the changes.

61
docs/developer_guide/index.md Normal file
View File

@ -0,0 +1,61 @@
# Developer Guide
All contributions to RenderCV are welcome!
The source code is thoroughly documented and well-commented, making it an enjoyable read and easy to understand. Also, a flowchart is provided below to help you understand how RenderCV works.
## Getting Started
1. Ensure that you have Python version 3.10 or higher.
2. Then, clone the repository recursively (because TinyTeX is being used as a submodule) with the following command.
```bash
git clone --recursive https://github.com/sinaatalay/rendercv.git
```
3. Go to the `rendercv` directory.
```bash
cd rendercv
```
4. Create a virtual environment.
```bash
python -m venv .venv
```
5. Activate the virtual environment.
=== "Windows (PowerShell)"
```powershell
.venv\Scripts\Activate.ps1
```
=== "MacOS/Linux"
```bash
source .venv/bin/activate
```
6. Install the dependencies.
```bash
pip install --editable .[docs,tests,dev]
```
## How RenderCV works?
The flowchart below illustrates the general operations of RenderCV. A detailed documentation of the source code is available in the [reference](../reference/index.md).
```mermaid
flowchart TD
A[YAML Input File] --parsing with ruamel.yaml package--> B(Python Dictionary)
B --validation with pydantic package--> C((Pydantic Object))
C --> D[LaTeX File]
C --> E[Markdown File]
E --markdown package--> K[HTML FIle]
D --TinyTeX--> L[PDF File]
L --PyMuPDF package--> Z[PNG Files]
AA[(Jinja2 Templates)] --> D
AA[(Jinja2 Templates)] --> E
```
## About [`pyproject.toml`](https://github.com/sinaatalay/rendercv/blob/main/pyproject.toml)
[`pyproject.toml`](https://github.com/sinaatalay/rendercv/blob/main/pyproject.toml) contains all the metadata, dependencies, and tools required for the project. Please read through the file to understand the project's technical details.

26
docs/developer_guide/testing.md Normal file
View File

@ -0,0 +1,26 @@
# Testing
After updating the code, ensure that all tests pass. To run the tests, use the following command.
```bash
pytest
```
Once new commits are pushed to the `main` branch, the [`test.yaml`](https://github.com/sinaatalay/rendercv/blob/main/.github/workflows/test.yaml) workflow will be automatically triggered, and the tests will run.
## [`testdata`](https://github.com/sinaatalay/rendercv/tree/main/tests/testdata) folder
In some of the tests:
- RenderCV generates an output with a sample input.
- Then, the output is compared with a reference output, which has been manually generated and stored in `testdata`. If the files differ, the tests fail.
When the `testdata` folder needs to be updated, it can be manually regenerated by setting `update_testdata` to `True` in `conftest.py` and running the tests.
!!! warning
- Whenever the `testdata` folder is generated, the files should be reviewed manually to ensure everything works as expected.
- `update_testdata` should be set to `False` before committing the changes.

45
docs/developer_guide/writing_documentation.md Normal file
View File

@ -0,0 +1,45 @@
# Writing Documentation
The documentation's source files are located in the [`docs`](https://github.com/sinaatalay/rendercv/tree/main/docs) directory and it is built using the [MkDocs](https://github.com/mkdocs/mkdocs) package. To work on the documentation and see the changes in real-time, run the following command.
```bash
mkdocs serve
```
Once the changes are pushed to the `main` branch, the [`deploy-docs`](https://github.com/sinaatalay/rendercv/blob/main/.github/workflows/deploy-docs.yaml) workflow will be automatically triggered, and [docs.rendercv.com](https://docs.rendercv.com/) will be updated to the most recent version.
## Updating the [`examples`](https://github.com/sinaatalay/rendercv/tree/main/examples) folder
The `examples` folder includes example YAML files for all the built-in themes, along with their corresponding PDF outputs. Also, there are PNG files of the first pages of each theme in [`docs/assets/images`](https://github.com/sinaatalay/rendercv/tree/main/docs/assets/images). These examples are shown in [`README.md`](https://github.com/sinaatalay/rendercv/blob/main/README.md).
These files are generated using [`docs/update_rendercv_files.py`](https://github.com/sinaatalay/rendercv/blob/main/docs/update_rendercv_files.py). The contents of the examples are taken from the [`get_a_sample_data_model`](https://docs.rendercv.com/reference/data_models/#rendercv.data_models.get_a_sample_data_model) function from [`data_models.py`](https://docs.rendercv.com/reference/data_models/).
Run the following command to update the `examples` folder.
```bash
python docs/update_rendercv_files.py
```
## Updating figures of the entry types in the "[Structure of the YAML Input File](https://docs.rendercv.com/user_guide/structure_of_the_yaml_input_file/)"
There are example figures for each entry type for each theme in the "[Structure of the YAML Input File](https://docs.rendercv.com/user_guide/structure_of_the_yaml_input_file/)" page.
The figures are generated using [`docs/update_rendercv_files.py`](https://github.com/sinaatalay/rendercv/blob/main/docs/update_rendercv_files.py).
Run the following command to update the figures.
```bash
python docs/update_rendercv_files.py
```
## Updating the [JSON Schema](https://github.com/sinaatalay/rendercv/blob/main/schema.json)
The schema of RenderCV's input file is defined using [Pydantic](https://docs.pydantic.dev/latest/). Pydantic allows automatic creation and customization of JSON schemas from Pydantic models.
The JSON Schema is also generated using [`docs/update_rendercv_files.py`](https://github.com/sinaatalay/rendercv/blob/main/docs/update_rendercv_files.py). It uses [`generate_json_schema`](https://docs.rendercv.com/reference/data_models/#rendercv.data_models.generate_json_schema) function from [`data_models.py`](https://docs.rendercv.com/reference/data_models/).
Run the following command to update the JSON Schema.
```bash
python docs/update_rendercv_files.py
```

52
docs/index.md
View File

@ -1,22 +1,30 @@
# RenderCV
<div align="center" markdown="span">
*A* $\LaTeX$ *CV/resume framework*
<br>
<br>
[![test](https://github.com/sinaatalay/rendercv/actions/workflows/test.yaml/badge.svg?branch=main)](https://github.com/sinaatalay/rendercv/actions/workflows/test.yaml)
[![coverage](https://coverage-badge.samuelcolvin.workers.dev/sinaatalay/rendercv.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/sinaatalay/rendercv)
[![docs](https://img.shields.io/badge/docs-mkdocs-rgb(0%2C79%2C144))](https://docs.rendercv.com)
[![pypi-version](https://img.shields.io/pypi/v/rendercv?label=PyPI%20version&color=rgb(0%2C79%2C144))](https://pypi.python.org/pypi/rendercv)
[![pypi-downloads](https://img.shields.io/pepy/dt/rendercv?label=PyPI%20downloads&color=rgb(0%2C%2079%2C%20144))](https://pypistats.org/packages/rendercv)
</div>
RenderCV is a $\LaTeX$ CV/resume framework. It allows you to create a high-quality CV as a PDF from a YAML file with full Markdown syntax support and complete control over the $\LaTeX$ code.
The primary motivation behind the RenderCV is to provide people with a concrete framework that will allow
RenderCV allows you to create a high-quality CV as a PDF from a YAML input file. It supports full Markdown syntax and gives you complete control over the $\LaTeX$ code.
- Version controlling a CV's content and design separately in an organized manner.
- Building an automated pipeline that can generate the CV as PDF, markdown, and PNG files.
The primary motivation behind the RenderCV is to provide people with a concrete framework that allows
- Version controlling a CV's content and design separately and in an organized manner.
- Building an automated pipeline that updates the final output (PDF, $\LaTeX$, Markdown, HTML, and PNGs) whenever the content is modified.
- Making the CV's design uniform and nicely structured without room for human errors.
RenderCV offers built-in $\LaTeX$ and Markdown templates ready to produce high-quality CVs. However, the templates are entirely arbitrary and can easily be updated to leverage RenderCV's capabilities with your custom CV themes.
RenderCV offers built-in $\LaTeX$ and Markdown templates ready to produce high-quality CVs. However, the templates are entirely arbitrary and can easily be updated to leverage RenderCV's capabilities with custom CV themes.
RenderCV takes a YAML file that looks like this:
@ -48,7 +56,7 @@ cv:
...
```
Then, it produces one of these PDFs with its corresponding $\LaTeX$ code, markdown file, and images as PNGs. Each of these is an example of one of four built-in themes of RenderCV. Click on images to preview PDFs.
Then, it produces one of these PDFs with its corresponding $\LaTeX$ code, Markdown file, HTML file, and images as PNGs. Each of these is an example of one of 4 built-in themes of RenderCV. Click on the images below to preview PDF files.
| [![Classic Theme Example of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/classic.png)](https://github.com/sinaatalay/rendercv/blob/main/examples/John_Doe_ClassicTheme_CV.pdf) | [![Sb2nov Theme Example of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/sb2nov.png)](https://github.com/sinaatalay/rendercv/blob/main/examples/John_Doe_Sb2novTheme_CV.pdf) |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -56,7 +64,7 @@ Then, it produces one of these PDFs with its corresponding $\LaTeX$ code, markdo
It also generates an HTML file so all the content can be pasted into Grammarly or any word processor for spelling and grammar checking.
The contents of the HTML file can be pasted into Grammarly or any word processor for spelling and grammar checking.
![Grammarly for RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/grammarly.gif)
@ -66,7 +74,7 @@ It also validates the input file, and if there are any problems, it tells users
![CLI of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/cli.gif)
RenderCV comes with a JSON Schema so that the input YAML file can be filled out interactively.
RenderCV comes with a JSON Schema so that the YAML input file can be filled out interactively.
![JSON Schema of RenderCV](https://raw.githubusercontent.com/sinaatalay/rendercv/main/docs/assets/images/schema.gif)
@ -75,8 +83,6 @@ RenderCV comes with a JSON Schema so that the input YAML file can be filled out
Either use [rendercv-pipeline](https://github.com/sinaatalay/rendercv-pipeline) or follow the steps below.
> 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 in a terminal to install RenderCV.
```bash
@ -86,13 +92,13 @@ Either use [rendercv-pipeline](https://github.com/sinaatalay/rendercv-pipeline)
```bash
rendercv new "Full Name"
```
4. Edit the contents of `Full_Name_CV.yaml` in your favorite editor (*tip: use an editor that supports JSON Schemas*). The templates can be modified as well.
4. Edit the contents of `Full_Name_CV.yaml` in your favorite editor (*tip: use an editor that supports JSON Schemas*).
5. Run the command below to generate your CV.
```bash
rendercv render Full_Name_CV.yaml
```
[Here](https://docs.rendercv.com/user_guide/), you can find a comprehensive user guide that covers the data model (YAML structure) and command-line interface (CLI) in greater detail.
[Here](https://docs.rendercv.com/user_guide/), you can find a comprehensive user guide that covers the structure of the YAML input file and command-line interface (CLI) in greater detail.
## Motivation
@ -100,11 +106,11 @@ Writing the content of a CV and designing a CV are separate issues that should b
RenderCV also provides a general set of utilities that will automate most of the manual work involved in the CV updating process. After updating a single sentence or a date in the YAML input file written in pure English, RenderCV will
- re-create your $\LaTeX$ file.
- render a new PDF file.
- create a new Markdown file.
- create a new HTML document to be pasted into word processors for spelling and grammar checking.
- create PNG files for each page.
- re-create your $\LaTeX$ file,
- render a new PDF file,
- create a new Markdown file,
- create a new HTML document, and
- create images of each page of the PDF file as PNGs.
> Why should I bother using RenderCV instead of $\LaTeX$? I can version-control $\LaTeX$ code too!
@ -113,15 +119,13 @@ RenderCV is not a replacement for $\LaTeX$, but it's a general set of utilities
Here are some advantages of RenderCV over using pure $\LaTeX$:
- RenderCV will separate the content of your CV from your $\LaTeX$ code. They will sit in independent files, and RenderCV will use both to generate your CV.
- You will be able to version-control your design and content separately.
- You will be able to version-control your $\LaTeX$ code and content separately.
- Updating your content in a YAML file is easier than updating a complex $\LaTeX$ file.
- A pure $\LaTeX$ CV will have many code duplications because a CV is a document with a list of sections that contain a list of entries. RenderCV has only one $\LaTeX$ code for each entry type, duplicated automatically based on the YAML input file.
- Spell-checking is not very straightforward in $\LaTeX$ documents.
## Documentation
The source code of RenderCV is well-commented and documented. Reading the source code might be fun as the software structure is explained with docstrings and comments.
The detailed user guide can be found [here](https://docs.rendercv.com/user_guide).
The developer guide can be found [here](https://docs.rendercv.com/developer_guide).
@ -132,10 +136,6 @@ The changelog can be found [here](https://docs.rendercv.com/changelog).
## Contributing
All contributions to RenderCV are welcome! For development, you will need to clone the repository recursively, as TinyTeX is being used as a submodule:
All contributions to RenderCV are welcome! To get started, please read [the developer guide](https://docs.rendercv.com/developer_guide).
```bash
git clone --recursive https://github.com/sinaatalay/rendercv.git
```
All code and development tool specifications are in `pyproject.toml`. Also, don't forget to read [the developer guide](https://docs.rendercv.com/developer_guide).
The source code is thoroughly documented and well-commented, making it an enjoyable read and easy to understand.

2
docs/reference/cli.md
View File

@ -1,3 +1,3 @@
# CLI
# `cli.py`
::: rendercv.cli

2
docs/reference/data_models.md
View File

@ -1,3 +1,3 @@
# Data Models
# `data_models.py`
::: rendercv.data_models

2
docs/reference/index.md
View File

@ -6,7 +6,7 @@ In this section, you can find how RenderCV's components are structured and how t
- [cli.py](cli.md) – This module contains all the command-line interface (CLI) related code for RenderCV.
- [data_models.py](data_models.md) – This module contains classes and functions to parse and validate RenderCV's input YAML.
- [renderer.py](renderer.md) – This module implements $\LaTeX$ file generation and $\LaTeX$ runner utilities for RenderCV.
- [renderer.py](renderer.md) – This module contains utilities for generating $\LaTeX$, Markdown, and HTML files, as well as running TinyTeX for RenderCV.
- [themes](themes/index.md) – This package contains all the built-in themes of RenderCV.
- [classic](themes/classic.md)
- [engineeringresumes](themes/engineeringresumes.md)

2
docs/reference/renderer.md
View File

@ -1,3 +1,3 @@
# Renderer
# `renderer.py`
::: rendercv.renderer

41
docs/update_rendercv_files.py
View File

@ -1,54 +1,21 @@
import tempfile
import pathlib
import importlib
import importlib.machinery
import importlib.util
import io
import os
import sys
import shutil
from typing import Any
import pdfCropMargins
import ruamel.yaml
# Import rendercv. I import the data_models and renderer modules like this instead
# of using `import rendercv` because in order for that to work, the current working
# directory must be the root of the project. To make it convenient for the user, I
# import the modules using the full path of the files.
import rendercv.cli as cli
import rendercv.data_models as dm
import rendercv.renderer as r
repository_root = pathlib.Path(__file__).parent.parent
rendercv_path = repository_root / "rendercv"
image_assets_directory = pathlib.Path(__file__).parent / "assets" / "images"
def import_a_module(module_name: str, file_path: pathlib.Path):
"""Imports a module from a file.
Args:
module_name (str): The name of the module.
file_path (pathlib.Path): The path to the file.
Returns:
Any: The imported module.
"""
spec = importlib.util.spec_from_file_location(module_name, file_path)
module = importlib.util.module_from_spec(spec) # type: ignore
sys.modules[module_name] = module
spec.loader.exec_module(module) # type: ignore
return module
# Import rendercv:
rendercv = import_a_module("rendercv", rendercv_path / "__init__.py")
# Import the rendercv.data_models as dm:
dm = import_a_module("rendercv.data_models", rendercv_path / "data_models.py")
# Import the rendercv.renderer as r:
r = import_a_module("rendercv.renderer", rendercv_path / "renderer.py")
# Import the rendercv.cli as cli:
cli = import_a_module("rendercv.cli", rendercv_path / "cli.py")
# The entries below will be pasted into the documentation as YAML, and their
# corresponding figures will be generated with this script.
education_entry = {

29
docs/user_guide/faq.md Normal file
View File

@ -0,0 +1,29 @@
# Frequently Asked Questions (FAQ)
## Can I use custom fonts?
To be answered.
## Can I add a background image?
To be answered.
## How good is it in terms of parseability by ATS?
To be answered.
## How to add links?
To be answered.
## How to use Greek letters?
To be answered.
## Can I add a profile picture?
To be answered.
## How can I switch the order of `company` and `position` in ExperienceEntry?
To be answered.

47
docs/user_guide/index.md
View File

@ -33,7 +33,7 @@ This command will create the following files:
- A directory called `markdown`.
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.
This directory contains the Markdown source code of RenderCV's default Markdown template. You can update its contents to tweak the Markdown and HTML output of the CV.
### Options of the `new` command
@ -71,12 +71,9 @@ This command will generate a directory called `rendercv_output`, which contains
- 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.
- Images of each page of the PDF file in PNG format, `Your_Name_CV_1.png`, `Your_Name_CV_page_2.png`, etc.
- The CV in Markdown format, `Your_Name_CV.md`.
- An HTML file from the Markdown file, `Your_Name_CV.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.
- The CV in HTML format, `Your_Name_CV.html`.
- 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.
@ -176,10 +173,10 @@ Each of these `*.j2.tex` files is $\LaTeX$ code with some Python in it. These fi
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)
- [templates of the `classic` theme](../reference/themes/classic.md)
- [templates of the `engineeringresumes` theme](../reference/themes/engineeringresumes.md)
- [templates of the `sb2nov` theme](../reference/themes/sb2nov.md)
- [templates of the `moderncv` theme](../reference/themes/moderncv.md)
For example, the content of `ExperienceEntry.j2.tex` for the `moderncv` theme is shown below:
@ -241,33 +238,3 @@ The `create-theme` command has some options:
```bash
rendercv create-theme "mycustomtheme" --based-on "THEME_NAME"
```
## Frequently Asked Questions (FAQ)
### Can I use custom fonts?
To be answered.
### Can I add a background image?
To be answered.
### How good is it in terms of parseability by ATS?
To be answered.
### How to add links?
To be answered.
### How to use Greek letters?
To be answered.
### Can I add a profile picture?
To be answered.
### How can I switch the order of `company` and `position` in ExperienceEntry?
To be answered.

9
mkdocs.yaml
View File

@ -9,6 +9,7 @@ edit_uri: edit/main/docs/
theme:
name: material
language: en
custom_dir: docs/overrides
palette:
- media: "(prefers-color-scheme: light)"
@ -51,7 +52,12 @@ nav:
- 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
- FAQ: user_guide/faq.md
- Developer Guide:
- Developer Guide: developer_guide/index.md
- Writing Documentation: developer_guide/writing_documentation.md
- Testing: developer_guide/testing.md
- FAQ: developer_guide/faq.md
- Reference:
- Reference: reference/index.md
- cli.py: reference/cli.md
@ -87,6 +93,7 @@ markdown_extensions:
plugins:
- search
- offline
- macros: # mkdocs-macros-plugin
module_name: docs/update_rendercv_files
- mkdocstrings:

3
pyproject.toml
View File

@ -104,9 +104,8 @@ rendercv = 'rendercv.__main__:app'
docs = [
"mkdocs-material==9.5.24", # to build docs
"mkdocstrings-python==1.10.3", # to build reference documentation from docstrings
"pdfCropMargins==2.1.2", # to generate entry figures for the documentation
"pdfCropMargins==2.1.3", # to generate entry figures for the documentation
"pillow==10.3.0", # lock the dependency of pdfCropMargins
"PySimpleGUI==4.60.5", # lock the dependency of pdfCropMargins
"mkdocs-macros-plugin==1.0.5", # to be able to have dynamic content in the documentation
]
tests = [

6
rendercv/__init__.py
View File

@ -1,8 +1,8 @@
"""RenderCV package.
RenderCV is a $\\LaTeX$ CV/resume framework that generates a CV from a JSON/YAML input
file. Its primary motivation is to allow the separation between a CV's content and
design.
RenderCV is a LaTeX CV/resume framework that allows you to create a high-quality CV as a
PDF from a YAML file with full Markdown syntax support and complete control over the
LaTeX code.
"""
__version__ = "1.11"

124
rendercv/renderer.py
View File

@ -5,8 +5,8 @@ files, Markdown files, HTML files, and PNG files from the data model.
The $\\LaTeX$ and Markdown files are generated with
[Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) templates. Then, the $\\LaTeX$
file is rendered into a PDF with [TinyTeX](https://yihui.org/tinytex/), a $\\LaTeX$
distribution. The markdown file is rendered into an HTML file with markdown package. The
PDF files are rendered into PNG files with PyMuPDF/fitz package.
distribution. The markdown file is rendered into an HTML file with `markdown` package.
The PDF files are rendered into PNG files with `PyMuPDF`/`fitz` package.
"""
import subprocess
@ -113,10 +113,13 @@ class LaTeXFile(TemplatedFile):
environment: jinja2.Environment,
):
latex_file_data_model = copy.deepcopy(data_model)
transformed_sections = transform_markdown_sections_to_latex_sections(
latex_file_data_model.cv.sections_input
)
latex_file_data_model.cv.sections_input = transformed_sections
if latex_file_data_model.cv.sections_input is not None:
transformed_sections = transform_markdown_sections_to_latex_sections(
latex_file_data_model.cv.sections_input
)
latex_file_data_model.cv.sections_input = transformed_sections
super().__init__(latex_file_data_model, environment)
def render_templates(self) -> tuple[str, str, list[tuple[str, list[str], str]]]:
@ -181,48 +184,10 @@ class LaTeXFile(TemplatedFile):
**kwargs,
)
result = self.revert_nested_latex_style_commands(result)
result = revert_nested_latex_style_commands(result)
return result
@classmethod
def revert_nested_latex_style_commands(cls, latex_string: str) -> str:
"""Revert the nested $\\LaTeX$ style commands to allow users to unbold or
unitalicize a bold or italicized text.
Args:
latex_string (str): The string to revert the nested $\\LaTeX$ style
commands.
Returns:
str: The string with the reverted nested $\\LaTeX$ style commands.
"""
# If there is nested \textbf, \textit, or \underline commands, replace the inner
# ones with \textnormal:
nested_commands_to_look_for = [
"textbf",
"textit",
"underline",
]
for command in nested_commands_to_look_for:
nested_commands = True
while nested_commands:
# replace all the inner commands with \textnormal until there are no
# nested commands left:
# find the first nested command:
nested_commands = re.findall(
rf"\\{command}{{[^}}]*?(\\{command}{{.*?}})", latex_string
)
# replace the nested command with \textnormal:
for nested_command in nested_commands:
new_command = nested_command.replace(command, "textnormal")
latex_string = latex_string.replace(nested_command, new_command)
return latex_string
def get_latex_code(self) -> str:
"""Get the $\\LaTeX$ code of the file.
@ -329,6 +294,44 @@ class MarkdownFile(TemplatedFile):
file_path.write_text(self.get_markdown_code(), encoding="utf-8")
def revert_nested_latex_style_commands(latex_string: str) -> str:
"""Revert the nested $\\LaTeX$ style commands to allow users to unbold or
unitalicize a bold or italicized text.
Args:
latex_string (str): The string to revert the nested $\\LaTeX$ style
commands.
Returns:
str: The string with the reverted nested $\\LaTeX$ style commands.
"""
# If there is nested \textbf, \textit, or \underline commands, replace the inner
# ones with \textnormal:
nested_commands_to_look_for = [
"textbf",
"textit",
"underline",
]
for command in nested_commands_to_look_for:
nested_commands = True
while nested_commands:
# replace all the inner commands with \textnormal until there are no
# nested commands left:
# find the first nested command:
nested_commands = re.findall(
rf"\\{command}{{[^}}]*?(\\{command}{{.*?}})", latex_string
)
# replace the nested command with \textnormal:
for nested_command in nested_commands:
new_command = nested_command.replace(command, "textnormal")
latex_string = latex_string.replace(nested_command, new_command)
return latex_string
def escape_latex_characters(latex_string: str, strict: bool = True) -> str:
"""Escape $\\LaTeX$ characters in a string.
@ -452,7 +455,7 @@ def markdown_to_latex(markdown_string: str) -> str:
def transform_markdown_sections_to_latex_sections(
sections: Optional[dict[str, dm.SectionInput]],
sections: dict[str, dm.SectionInput],
) -> Optional[dict[str, dm.SectionInput]]:
"""
Recursively loop through sections and convert all the markdown strings (user input
@ -464,9 +467,6 @@ def transform_markdown_sections_to_latex_sections(
Returns:
Optional[dict[str, dm.SectionInput]]: Sections with $\\LaTeX$ strings.
"""
if sections is None:
return None
for key, value in sections.items():
# loop through the list and apply markdown_to_latex and escape_latex_characters
# to each item:
@ -541,8 +541,10 @@ def make_matched_part_something(
str: The string with the matched part something.
"""
if match_str is None:
# If the match_str is None, the whole string will be made something:
value = f"\\{something}{{{value}}}"
elif match_str in value and match_str != "":
# If the match_str is in the value, then make the matched part something:
value = value.replace(match_str, f"\\{something}{{{match_str}}}")
return value
@ -723,6 +725,17 @@ def get_an_item_with_a_specific_attribute_value(
) -> Any:
"""Get an item from a list of items with a specific attribute value.
Example:
```python
get_an_item_with_a_specific_attribute_value(
[item1, item2], # where item1.name = "John" and item2.name = "Jane"
"name",
"Jane"
)
```
will return:
`item2`
This function can be used as a Jinja2 filter in templates.
Args:
@ -741,8 +754,8 @@ def get_an_item_with_a_specific_attribute_value(
else:
if getattr(item, attribute) == value:
return item
return None
else:
return None
# Only one Jinja2 environment is needed for all the templates:
@ -976,6 +989,15 @@ def latex_to_pdf(
raise OSError(f"TinyTeX doesn't support the platform {sys.platform}!")
executable = executables[sys.platform]
# check if the executable exists:
if not executable.is_file():
raise FileNotFoundError(
f"The TinyTeX executable ({executable}) doesn't exist! If you are"
" cloning the repository, make sure to clone it recursively to get the"
" TinyTeX binaries. See the developer guide for more information."
)
# Run TinyTeX:
command = [
executable,