Skip to content

Commit 18ee0c0

Browse files
koxudaxikoxudaxi
authored
docs: Improve landing page, README, and add FAQ with GitHub issue links (#2680)
* docs: enhance landing page and README with emoji categorization and improved structure * docs: update landing page and README with detailed project usage examples * docs: fix markdown linting issues
1 parent 9ab21c8 commit 18ee0c0

33 files changed

Lines changed: 1175 additions & 1582 deletions

‎README.md‎

Lines changed: 169 additions & 547 deletions
Large diffs are not rendered by default.

‎docs/aliases.md‎

Lines changed: 16 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
# Field Aliases
1+
# 🏷️ Field Aliases
22

33
The `--aliases` option allows you to rename fields in the generated models. This is useful when you want to use different Python field names than those defined in the schema while preserving the original names as serialization aliases.
44

5-
## Basic Usage
5+
## 🚀 Basic Usage
66

77
```bash
88
datamodel-codegen --input schema.json --output model.py --aliases aliases.json
99
```
1010

11-
## Alias File Format
11+
## 📋 Alias File Format
1212

1313
The alias file is a JSON file that maps original field names to their Python aliases.
1414

15-
### Flat Format (Traditional)
15+
### 📝 Flat Format (Traditional)
1616

1717
The simplest format applies aliases to all fields with the matching name, regardless of which class they belong to:
1818

@@ -26,7 +26,7 @@ The simplest format applies aliases to all fields with the matching name, regard
2626

2727
This will rename all fields named `id` to `id_`, all fields named `type` to `type_`, etc.
2828

29-
### Scoped Format (Class-Specific)
29+
### 🎯 Scoped Format (Class-Specific)
3030

3131
When you have the same field name in multiple classes but want different aliases for each, use the scoped format with `ClassName.field`:
3232

@@ -38,14 +38,15 @@ When you have the same field name in multiple classes but want different aliases
3838
}
3939
```
4040

41-
**Priority**: Scoped aliases take priority over flat aliases. In the example above:
41+
**⚡ Priority**: Scoped aliases take priority over flat aliases. In the example above:
42+
4243
- `User.name` will be renamed to `user_name`
4344
- `Address.name` will be renamed to `address_name`
4445
- Any other class with a `name` field will use `default_name`
4546

46-
## Example
47+
## 📝 Example
4748

48-
### Input Schema
49+
### 📥 Input Schema
4950

5051
```json
5152
{
@@ -73,7 +74,7 @@ When you have the same field name in multiple classes but want different aliases
7374
}
7475
```
7576

76-
### Alias File
77+
### 🏷️ Alias File
7778

7879
```json
7980
{
@@ -83,7 +84,7 @@ When you have the same field name in multiple classes but want different aliases
8384
}
8485
```
8586

86-
### Generated Output
87+
### ✨ Generated Output
8788

8889
```python
8990
from pydantic import BaseModel, Field
@@ -102,12 +103,14 @@ class Root(BaseModel):
102103
address: Address | None = None
103104
```
104105

105-
## Notes
106+
## 📌 Notes
106107

107108
- The `ClassName` in scoped format must match the generated Python class name (after title conversion)
108109
- When using `--use-title-as-name`, the class name is derived from the `title` property in the schema
109110
- Aliases are applied during code generation, so the original field names are preserved as Pydantic `alias` values for proper serialization/deserialization
110111

111-
## See Also
112+
---
113+
114+
## 📖 See Also
112115

113-
- [CLI Reference: `--aliases`](cli-reference/field-customization.md#aliases) - Detailed CLI option documentation with examples
116+
- 🖥️ [CLI Reference: `--aliases`](cli-reference/field-customization.md#aliases) - Detailed CLI option documentation with examples

‎docs/cli-reference/base-options.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Base Options
1+
# 📁 Base Options
22

3-
## Options
3+
## 📋 Options
44

55
| Option | Description |
66
|--------|-------------|

‎docs/cli-reference/field-customization.md‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Field Customization
1+
# 🏷️ Field Customization
22

3-
## Options
3+
## 📋 Options
44

55
| Option | Description |
66
|--------|-------------|
@@ -34,9 +34,6 @@ Apply custom field and class name aliases from JSON file.
3434
The `--aliases` option allows renaming fields and classes via a JSON mapping file,
3535
providing fine-grained control over generated names independent of schema definitions.
3636

37-
!!! tip "See Also"
38-
For detailed explanation and examples, see [Field Aliases](../aliases.md).
39-
4037
!!! tip "Usage"
4138

4239
```bash
@@ -856,9 +853,6 @@ The `--field-constraints` flag generates Pydantic Field() definitions with
856853
validation constraints (min/max length, pattern, etc.) from the schema.
857854
Output differs between Pydantic v1 and v2 due to API changes.
858855

859-
!!! tip "See Also"
860-
For detailed explanation and mypy compatibility, see [Field Constraints](../field-constraints.md).
861-
862856
!!! tip "Usage"
863857

864858
```bash

‎docs/cli-reference/general-options.md‎

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# General Options
1+
# ⚙️ General Options
22

3-
## Options
3+
## 📋 Options
44

55
| Option | Description |
66
|--------|-------------|
@@ -1389,9 +1389,6 @@ The `--generate-pyproject-config` flag outputs a pyproject.toml configuration
13891389
snippet based on the provided CLI arguments. This is useful for converting
13901390
a working CLI command into a reusable configuration file.
13911391

1392-
!!! tip "See Also"
1393-
For pyproject.toml configuration guide, see [pyproject.toml Configuration](../pyproject_toml.md).
1394-
13951392
!!! tip "Usage"
13961393

13971394
```bash
@@ -1598,9 +1595,6 @@ The `--ignore-pyproject` flag tells datamodel-codegen to ignore any
15981595
when you want to override project defaults with CLI arguments, or when
15991596
testing without project configuration.
16001597

1601-
!!! tip "See Also"
1602-
For pyproject.toml configuration guide, see [pyproject.toml Configuration](../pyproject_toml.md).
1603-
16041598
!!! tip "Usage"
16051599

16061600
```bash

‎docs/cli-reference/index.md‎

Lines changed: 10 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,20 @@
1-
# CLI Reference
1+
# 🖥️ CLI Reference
22

33
This documentation is auto-generated from test cases.
44

5-
**[Quick Reference](quick-reference.md)** - All options on one page for Ctrl+F search
5+
🔍 **[Quick Reference](quick-reference.md)** - All options on one page for Ctrl+F search
66

7-
## Related Documentation
8-
9-
| Topic | Description |
10-
|-------|-------------|
11-
| [Generate from OpenAPI](../openapi.md) | OpenAPI schema generation guide |
12-
| [Generate from JSON Schema](../jsonschema.md) | JSON Schema generation guide |
13-
| [Generate from GraphQL](../graphql.md) | GraphQL schema generation guide |
14-
| [pyproject.toml Configuration](../pyproject_toml.md) | File-based configuration |
15-
| [Custom Templates](../custom_template.md) | Jinja2 template customization |
16-
| [Field Aliases](../aliases.md) | Field renaming with aliases |
17-
| [Root Models and Type Aliases](../root-model-and-type-alias.md) | Type alias generation |
18-
19-
## Categories
7+
## 📂 Categories
208

219
| Category | Options | Description |
2210
|----------|---------|-------------|
23-
| [Base Options](base-options.md) | 5 | Input/output configuration |
24-
| [Typing Customization](typing-customization.md) | 16 | Type annotation and import behavior |
25-
| [Field Customization](field-customization.md) | 20 | Field naming and docstring behavior |
26-
| [Model Customization](model-customization.md) | 26 | Model generation behavior |
27-
| [Template Customization](template-customization.md) | 15 | Output formatting and custom rendering |
28-
| [OpenAPI-only Options](openapi-only-options.md) | 5 | OpenAPI-specific features |
29-
| [General Options](general-options.md) | 11 | Utilities and meta options |
11+
| 📁 [Base Options](base-options.md) | 5 | Input/output configuration |
12+
| 🔧 [Typing Customization](typing-customization.md) | 16 | Type annotation and import behavior |
13+
| 🏷️ [Field Customization](field-customization.md) | 20 | Field naming and docstring behavior |
14+
| 🏗️ [Model Customization](model-customization.md) | 26 | Model generation behavior |
15+
| 🎨 [Template Customization](template-customization.md) | 15 | Output formatting and custom rendering |
16+
| 📘 [OpenAPI-only Options](openapi-only-options.md) | 5 | OpenAPI-specific features |
17+
| ⚙️ [General Options](general-options.md) | 11 | Utilities and meta options |
3018

3119
## All Options
3220

‎docs/cli-reference/model-customization.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Model Customization
1+
# 🏗️ Model Customization
22

3-
## Options
3+
## 📋 Options
44

55
| Option | Description |
66
|--------|-------------|

‎docs/cli-reference/openapi-only-options.md‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
1-
# OpenAPI-only Options
1+
# 📘 OpenAPI-only Options
22

3-
!!! info "Related Documentation"
4-
For OpenAPI usage guide and examples, see [Generate from OpenAPI](../openapi.md).
5-
6-
## Options
3+
## 📋 Options
74

85
| Option | Description |
96
|--------|-------------|

‎docs/cli-reference/quick-reference.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
# Quick Reference
1+
# 🔍 Quick Reference
22

33
All CLI options in one page for easy **Ctrl+F** searching.
44

5-
Click any option to see detailed documentation with examples.
5+
👆 Click any option to see detailed documentation with examples.
66

77
---
88

99
```text
1010
datamodel-codegen [OPTIONS]
1111
```
1212

13-
## All Options by Category
13+
## 📂 All Options by Category
1414

15-
### Base Options
15+
### 📁 Base Options
1616

1717
| Option | Description |
1818
|--------|-------------|
@@ -22,7 +22,7 @@ datamodel-codegen [OPTIONS]
2222
| [`--output`](base-options.md#output) | Specify the destination path for generated Python code. |
2323
| [`--url`](base-options.md#url) | Fetch schema from URL with custom HTTP headers. |
2424

25-
### Typing Customization
25+
### 🔧 Typing Customization
2626

2727
| Option | Description |
2828
|--------|-------------|
@@ -43,7 +43,7 @@ datamodel-codegen [OPTIONS]
4343
| [`--use-union-operator`](typing-customization.md#use-union-operator) | Test GraphQL annotated types with standard collections and union operator. |
4444
| [`--use-unique-items-as-set`](typing-customization.md#use-unique-items-as-set) | Generate set types for arrays with uniqueItems constraint. |
4545

46-
### Field Customization
46+
### 🏷️ Field Customization
4747

4848
| Option | Description |
4949
|--------|-------------|
@@ -68,7 +68,7 @@ datamodel-codegen [OPTIONS]
6868
| [`--use-schema-description`](field-customization.md#use-schema-description) | Use schema description as class docstring. |
6969
| [`--use-title-as-name`](field-customization.md#use-title-as-name) | Use schema title as the generated class name. |
7070

71-
### Model Customization
71+
### 🏗️ Model Customization
7272

7373
| Option | Description |
7474
|--------|-------------|
@@ -99,7 +99,7 @@ datamodel-codegen [OPTIONS]
9999
| [`--use-serialize-as-any`](model-customization.md#use-serialize-as-any) | Wrap fields with subtypes in Pydantic's SerializeAsAny. |
100100
| [`--use-subclass-enum`](model-customization.md#use-subclass-enum) | Generate typed Enum subclasses for enums with specific field types. |
101101

102-
### Template Customization
102+
### 🎨 Template Customization
103103

104104
| Option | Description |
105105
|--------|-------------|
@@ -119,7 +119,7 @@ datamodel-codegen [OPTIONS]
119119
| [`--use-exact-imports`](template-customization.md#use-exact-imports) | Import exact types instead of modules. |
120120
| [`--wrap-string-literal`](template-customization.md#wrap-string-literal) | Wrap long string literals across multiple lines. |
121121

122-
### OpenAPI-only Options
122+
### 📘 OpenAPI-only Options
123123

124124
| Option | Description |
125125
|--------|-------------|
@@ -129,7 +129,7 @@ datamodel-codegen [OPTIONS]
129129
| [`--use-operation-id-as-name`](openapi-only-options.md#use-operation-id-as-name) | Use OpenAPI operationId as the generated function/class name. |
130130
| [`--validation`](openapi-only-options.md#validation) | Enable validation constraints (deprecated, use --field-constraints). |
131131

132-
### General Options
132+
### ⚙️ General Options
133133

134134
| Option | Description |
135135
|--------|-------------|
@@ -147,7 +147,7 @@ datamodel-codegen [OPTIONS]
147147

148148
---
149149

150-
## Alphabetical Index
150+
## 🔤 Alphabetical Index
151151

152152
All options sorted alphabetically:
153153

‎docs/cli-reference/template-customization.md‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Template Customization
1+
# 🎨 Template Customization
22

3-
## Options
3+
## 📋 Options
44

55
| Option | Description |
66
|--------|-------------|
@@ -471,9 +471,6 @@ as a module path (e.g., "mymodule.formatter_function"). This is useful for
471471
adding custom comments, modifying code structure, or applying project-specific
472472
formatting rules beyond what black/isort provide.
473473

474-
!!! tip "See Also"
475-
For detailed explanation and examples, see [Custom Code Formatters](../custom-formatters.md).
476-
477474
!!! tip "Usage"
478475

479476
```bash
@@ -608,9 +605,6 @@ to override the default templates used for generating data models. This enables
608605
the generated code structure and formatting. Use with `--extra-template-data` to pass additional data
609606
to the templates.
610607

611-
!!! tip "See Also"
612-
For detailed explanation and examples, see [Custom Templates](../custom_template.md).
613-
614608
!!! tip "Usage"
615609

616610
```bash
@@ -1927,9 +1921,6 @@ the generated Python code. Available formatters are: black, isort,
19271921
ruff, yapf, autopep8, autoflake. Default is [black, isort].
19281922
Use this to customize formatting or disable formatters entirely.
19291923

1930-
!!! tip "See Also"
1931-
For built-in formatting configuration, see [Formatting](../formatting.md).
1932-
19331924
!!! tip "Usage"
19341925

19351926
```bash

0 commit comments

Comments
 (0)