mirror of
https://github.com/rendercv/rendercv.git
synced 2026-04-18 22:08:47 -04:00
Massive Refactor: Architecture Redesign and Technical Debt Cleanup (#528)
* Rename `data` folder with schema * Start refactoring data models * Work on entry models * Keep working on entries * Keep working on data models * Push old data files * Keep working on data models * First draft of schema.cv * Keep working on schema * Keep working on schema * Improve schema.models * Keep working on rendercv.schema * Work on schema.design * Keep working on rendercv.schema * Complete variant_class_generator * Keep working rendercv.schema * Keep working on rendercv.schema * Final touches to rendercv.schema * Improve json schema descriptions in rendercv.schema * Start working on rendercv.schema tests * Keep implementing rendercv.schema tests * Add more tests for rendercv.schema * Improve rendercv.schema * Improve docstrings and comments in rendercv.schema * Implement better pydantic error handling in `rendercv.schema` * Improve variant class system * Fix rendercv.schema tests * Start working on rendercv.templater * Update template names * Switching to new rendercv typst template soon * Work on new templater * Rename renderer with renderer_old * Don't use utils in rendercv.schema * Complete connections * Update renderer folder structure * Work on new renderer * Work on new renderer * Date processing on new renderer * Improve date processing, support multiple emails, phones, and websites * Improve markdown to Typst * Complete entry template processing * Time span computation in new renderer * Better entry templates * Setup new templates * Improve rendercv.schema * Start adding tests for rendercv.renderer * New markdown parser! * Improve markdown to typst conversion * Finalize markdown parser * Add new test files for rendercv.renderer * Fix cv and connections * Add connections test * Improve connection tests * Improve entry templates * Add model processor tests * Improve templater * Rename old folders * Improve schema * Add file generation logic to renderer * Fix naming issues * Fix schema tests * Add path type tests * Add font family and typst dimension type tests * Rename old tests * Fix design tests * Start integration testing of renderer * Improve entry tempates * Handle nested highlights properly * Finalize Typst preamble template * Start working on new CLI * Remove old test files * Implement override dictionary in new schema * Start working on new CLI * Better prints on render command * New structure * New render printer * Add all the commands to new CLI * Work on new command in new cli * Improve new command * Add error handler to new cli * Work on create theme command * Complete create theme command * Remove old source files * Improve exceptions * Create new docs * Add writing tests guide * Fix cli printer and write tests * Test copy templates * Add app tests * Bring back accidentally removed files * Imporve cli and tests * Fix path issues * Improve * Improve * Add reference file comparison tests * Fix path resolver * Start working on test_pdf_png * Implement comparison of multiple files (png) * Start testing typst * Fix templating issues * Fix header and entry templates issues * Implement short second rows * Fix date issues * Fix nested bullets and add summary * Update testdata * Implement footer * Update testdata * Reimagined design and locale schema, first iteration * Reimagined design and locale second iteration * Update design and locale schemas * Adapt templater to the new design and locale * Fix tests * Update lib.typ and testdata for the new locale and design * Implement proper tests with all combinations of entries * Remove some docstrings * fix connections logic * Improve * Start working on examples * Update testdata * Fix long second row issue * fix templating issues * Fix lib.typ issues * Update testdata * Fix clean_trailing_parts * Update test cv * update test cv * Update theme defaults * update schema and fix moderncv * Fix moderncv issues * Update testdata * Update testdata and examples * Fix issues about photo * Fix typst photo path issues * improve entry templates from yaml * add new locale * Rename writing tests doc * Update writing tests * Improve tests * Add more cli tests * Increase test coverage * Rename variant pydantic model generator * Improve tests * Update testdata and improve tests * Format, fix pre-commit errors * Fix scripts and update entry figures * Improve tests * Write docstrings of schema * Write schema docstrings * Setup api reference * Start working on new docs * Work on docs * Improve progress panel of render command * Finalize new docs index * Complete CLI docs * Work on YAML input structure page * Finalize user guide * Start working on developer guide * Improve api reference * Improve developer guide * Improve developer guide * Improve developer gide * Improve developer guide * Improve developer guide * Update developer guide * Improve developer guide * Improve developer guide * Improve developer guide * Developer guide first draft * update developer guide * Update examples * Update testdata * Handle wrong installation (rendercv instead of rendercv[full]) * Remove unnecessary files * Write set up vs code page * Update README.md * Change docs description * Compress design options gif * minor updates * Polish all the json schema descriptions * Update testdata and examples * Remove some emdashed from docs * Add whatsapp support * Add TestEscapeTypstCharacters to tests * Implement custom connections * Add page break before sections feature * Revert page break before sections feature * Rebase to main * Fix social network tests, update schema
This commit is contained in:
Sina Atalay
57
docs/developer_guide/code_guidelines/source_code.md
Normal file
57
docs/developer_guide/code_guidelines/source_code.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Guidelines for Writing Source Code
|
||||
|
||||
## Type Annotations
|
||||
|
||||
**Every function, variable, and class attribute must be strictly typed. No exceptions.**
|
||||
|
||||
Use modern Python 3.12+ syntax:
|
||||
|
||||
- Type aliases with `type` statement
|
||||
- PEP 695 type parameters (`[T]`, `[**P]`)
|
||||
- Pipe unions (`str | int`, not `Union[str, int]`)
|
||||
- Proper optional types (`str | None`, not `Optional[str]`)
|
||||
|
||||
## Linting and Type Checking
|
||||
|
||||
Always run `just check` and `just format` before committing. `just check` must show **zero errors**:
|
||||
|
||||
```bash
|
||||
just format
|
||||
just check
|
||||
```
|
||||
|
||||
If there's absolutely no alternative, use `# pyright: ignore[errorCode]` or `#NOQA: errorCode` to ignore typing or linting errors.
|
||||
|
||||
## Docstrings
|
||||
|
||||
Use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings). Include a **"Why" section** and **"Example" section** when it adds value:
|
||||
|
||||
```python
|
||||
def resolve_relative_path(
|
||||
path: pathlib.Path, info: pydantic.ValidationInfo, must_exist: bool = True
|
||||
) -> pathlib.Path:
|
||||
"""Convert relative path to absolute path based on input file location.
|
||||
|
||||
Why:
|
||||
Users reference files like `photo: profile.jpg` relative to their CV
|
||||
YAML. This validator resolves such paths to absolute form and validates
|
||||
existence, enabling file access during rendering.
|
||||
|
||||
Args:
|
||||
path: Path to resolve (may be relative or absolute).
|
||||
info: Validation context containing input file path.
|
||||
must_exist: Whether to raise error if path doesn't exist.
|
||||
|
||||
Returns:
|
||||
Absolute path.
|
||||
"""
|
||||
```
|
||||
|
||||
Docstring order:
|
||||
|
||||
1. Brief description (one line)
|
||||
2. Why section (when it adds value)
|
||||
3. Example section (when it adds value)
|
||||
4. Args section (mandatory)
|
||||
5. Returns section (mandatory)
|
||||
6. Raises section (mandatory if function raises exceptions)
|
||||
145
docs/developer_guide/code_guidelines/tests.md
Normal file
145
docs/developer_guide/code_guidelines/tests.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# Guidelines for Writing Tests
|
||||
|
||||
## File Structure
|
||||
|
||||
Each test file tests all classes and functions in its corresponding source file. The structure mirrors `src/rendercv/`:
|
||||
|
||||
```
|
||||
src/rendercv/renderer/templater/date.py
|
||||
→ tests/renderer/templater/test_date.py
|
||||
(tests all functions and classes in date.py)
|
||||
|
||||
src/rendercv/schema/models/cv/section.py
|
||||
→ tests/schema/models/cv/test_section.py
|
||||
(tests all functions and classes in section.py)
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
Test names must include the name of the function or class being tested.
|
||||
|
||||
**When you need only one test**, use `test_` + the name:
|
||||
|
||||
- Testing `clean_url()` → `test_clean_url`
|
||||
- Testing `Cv` → `test_cv`
|
||||
|
||||
**When you need multiple tests**, wrap them in a class using `Test` + PascalCase name:
|
||||
|
||||
- Testing `clean_url()` → `TestCleanUrl`
|
||||
- Testing `Cv` → `TestCv`
|
||||
|
||||
Example with one test:
|
||||
|
||||
```python
|
||||
@pytest.mark.parametrize(
|
||||
("url", "expected_clean_url"),
|
||||
[
|
||||
("https://example.com", "example.com"),
|
||||
("https://example.com/", "example.com"),
|
||||
("https://example.com/test", "example.com/test"),
|
||||
],
|
||||
)
|
||||
def test_clean_url(url, expected_clean_url):
|
||||
assert clean_url(url) == expected_clean_url
|
||||
```
|
||||
|
||||
Example with multiple tests:
|
||||
|
||||
```python
|
||||
class TestComputeDateString:
|
||||
@pytest.mark.parametrize(...)
|
||||
def test_date_parameter_takes_precedence(self, ...):
|
||||
...
|
||||
|
||||
@pytest.mark.parametrize(...)
|
||||
def test_date_ranges(self, ...):
|
||||
...
|
||||
|
||||
@pytest.mark.parametrize(...)
|
||||
def test_returns_none_for_incomplete_data(self, ...):
|
||||
...
|
||||
```
|
||||
|
||||
## Use Parametrize for Variations
|
||||
|
||||
Instead of writing multiple similar tests, use `@pytest.mark.parametrize`:
|
||||
|
||||
```python
|
||||
@pytest.mark.parametrize(
|
||||
("input_a", "input_b", "expected"),
|
||||
[
|
||||
("2020-01-01", "2021-01-01", "Jan 2020 – Jan 2021"),
|
||||
("2020-01", "2021-02-01", "Jan 2020 – Feb 2021"),
|
||||
(2020, 2021, "2020 – 2021"),
|
||||
],
|
||||
)
|
||||
def test_date_ranges(self, input_a, input_b, expected):
|
||||
result = compute_date_string(None, input_a, input_b, EnglishLocale())
|
||||
assert result == expected
|
||||
```
|
||||
|
||||
## Shared Fixtures with conftest.py
|
||||
|
||||
Place shared fixtures in `conftest.py`. Use the closest one possible:
|
||||
|
||||
- Fixtures for one folder → that folder's `conftest.py`
|
||||
- Fixtures for multiple folders → their closest common parent's `conftest.py`
|
||||
|
||||
```
|
||||
tests/
|
||||
├── conftest.py # Used across all tests
|
||||
├── schema/
|
||||
│ ├── conftest.py # Used by schema tests only
|
||||
│ └── models/
|
||||
│ └── cv/
|
||||
│ ├── conftest.py # Used by CV model tests only
|
||||
│ ├── test_section.py
|
||||
│ └── test_cv.py
|
||||
└── renderer/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Testing Principles
|
||||
|
||||
**Keep tests focused.** Test functions in isolation: input → output.
|
||||
|
||||
**Don't create unnecessary fixtures.** If setup is one clear line, inline it:
|
||||
|
||||
```python
|
||||
# Don't:
|
||||
@pytest.fixture
|
||||
def locale(self):
|
||||
return EnglishLocale()
|
||||
|
||||
def test_something(self, locale):
|
||||
result = format_date(Date(2020, 1, 1), locale)
|
||||
|
||||
# Do:
|
||||
def test_something(self):
|
||||
result = format_date(Date(2020, 1, 1), EnglishLocale())
|
||||
```
|
||||
|
||||
**Prefer real behavior over mocking.** Only mock when there's no practical alternative (external APIs, file system, etc.).
|
||||
|
||||
**Name tests by expected behavior, not by input:**
|
||||
|
||||
- Good: `test_returns_none_for_incomplete_data` - describes what should happen
|
||||
- Bad: `test_function_with_none_input` - describes input but not behavior
|
||||
|
||||
**Keep tests simple:**
|
||||
|
||||
```python
|
||||
def test_something(self, input, expected):
|
||||
result = function_under_test(input)
|
||||
assert result == expected
|
||||
```
|
||||
|
||||
**What to test:**
|
||||
|
||||
- Input → expected output
|
||||
- Input → expected error
|
||||
|
||||
**What to avoid:**
|
||||
|
||||
- Testing implementation details instead of behavior
|
||||
- Complex test setup when simple values work
|
||||
Reference in New Issue
Block a user