diff --git a/README.md b/README.md index 3328cf1..537c4b0 100644 --- a/README.md +++ b/README.md @@ -11,15 +11,15 @@ -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. \ No newline at end of file diff --git a/docs/changelog.md b/docs/changelog.md index c86cff8..7b695f5 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -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) -## [1.11] - 2024-06-01 + ## [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. diff --git a/docs/developer_guide.md b/docs/developer_guide.md deleted file mode 100644 index 98bbb76..0000000 --- a/docs/developer_guide.md +++ /dev/null @@ -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. diff --git a/docs/developer_guide/faq.md b/docs/developer_guide/faq.md new file mode 100644 index 0000000..3a8044c --- /dev/null +++ b/docs/developer_guide/faq.md @@ -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. diff --git a/docs/developer_guide/index.md b/docs/developer_guide/index.md new file mode 100644 index 0000000..d3a55a0 --- /dev/null +++ b/docs/developer_guide/index.md @@ -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. \ No newline at end of file diff --git a/docs/developer_guide/testing.md b/docs/developer_guide/testing.md new file mode 100644 index 0000000..11231ee --- /dev/null +++ b/docs/developer_guide/testing.md @@ -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. + + + diff --git a/docs/developer_guide/writing_documentation.md b/docs/developer_guide/writing_documentation.md new file mode 100644 index 0000000..43cd3b5 --- /dev/null +++ b/docs/developer_guide/writing_documentation.md @@ -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 +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 27a9a0f..7cefbf4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,30 @@ # RenderCV
+ +*A* $\LaTeX$ *CV/resume framework* + +
+
+ [![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) +
-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. \ No newline at end of file diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 28681d4..2db2166 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1,3 +1,3 @@ -# CLI +# `cli.py` ::: rendercv.cli \ No newline at end of file diff --git a/docs/reference/data_models.md b/docs/reference/data_models.md index d7af685..f89c9a7 100644 --- a/docs/reference/data_models.md +++ b/docs/reference/data_models.md @@ -1,3 +1,3 @@ -# Data Models +# `data_models.py` ::: rendercv.data_models \ No newline at end of file diff --git a/docs/reference/index.md b/docs/reference/index.md index 82b1ab7..b9b8219 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -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) diff --git a/docs/reference/renderer.md b/docs/reference/renderer.md index f93bbf1..ac2e21a 100644 --- a/docs/reference/renderer.md +++ b/docs/reference/renderer.md @@ -1,3 +1,3 @@ -# Renderer +# `renderer.py` ::: rendercv.renderer \ No newline at end of file diff --git a/docs/update_rendercv_files.py b/docs/update_rendercv_files.py index 6e40389..f7eaf51 100644 --- a/docs/update_rendercv_files.py +++ b/docs/update_rendercv_files.py @@ -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 = { diff --git a/docs/user_guide/faq.md b/docs/user_guide/faq.md new file mode 100644 index 0000000..089c73b --- /dev/null +++ b/docs/user_guide/faq.md @@ -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. \ No newline at end of file diff --git a/docs/user_guide/index.md b/docs/user_guide/index.md index 6ccc55c..69cb418 100644 --- a/docs/user_guide/index.md +++ b/docs/user_guide/index.md @@ -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. \ No newline at end of file diff --git a/mkdocs.yaml b/mkdocs.yaml index a461aa4..bcab5ee 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -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: diff --git a/pyproject.toml b/pyproject.toml index a1badd9..4c3dc76 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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 = [ diff --git a/rendercv/__init__.py b/rendercv/__init__.py index 3ae32d4..c1cd6f1 100644 --- a/rendercv/__init__.py +++ b/rendercv/__init__.py @@ -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" diff --git a/rendercv/renderer.py b/rendercv/renderer.py index fdc3795..9872ace 100644 --- a/rendercv/renderer.py +++ b/rendercv/renderer.py @@ -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,