Cookiecutter README 动态更新技巧

动态更新 README.md 的挑战

在 Cookiecutter 项目中，根据用户在 cookiecutter.json 中配置的选项（例如，是否包含 GUI 结构、是否使用 Sphinx 文档等），项目生成后可能需要移除或添加特定的文件和文件夹。相应地，项目的 README.md 文件中描述项目结构的章节也需要同步更新，以准确反映最终的项目布局。

最初尝试的方案是利用 post_gen_project.py 脚本在项目生成后读取 README.md，然后根据 cookiecutter 变量的值逐行判断并跳过不应显示的内容。然而，这种方法在实际操作中遇到了问题，导致某些行未能正确移除，甚至整个章节被跳过。

推荐方案：直接在 README.md 模板中使用 Jinja 条件逻辑

最简洁、最符合 Cookiecutter 设计哲学的方法是直接在 README.md 文件本身（作为 Jinja 模板）中使用 Jinja 的条件语句。Cookiecutter 在生成项目时会渲染所有的模板文件，因此，将条件逻辑嵌入到 README.md 中，可以让 Jinja 引擎在渲染阶段就根据 cookiecutter.json 中的变量值来决定哪些内容应该被包含，哪些应该被省略。

示例：改造 README.md 模板

假设 cookiecutter.json 中包含以下布尔类型变量：

{
    "include_gui_structure": false,
    "include_data_science_structure": false,
    "use_pre_commits": true,
    "use_sphinx_documentation": true
}

原始 README.md 中描述项目结构的部分可能如下：

    ├── assets             <- Folder for storing assets like images 
    ├── data               <- Folder for storing your data 
    ├── docs               <- A default Sphinx project; see sphinx-doc.org for details
    ├── models             <- Trained and serialized models, model predictions, or model summaries
    ├── notebooks          <- Jupyter notebooks
    |
    ├── src                <- Source code for use in this project
    │   ├── data           <- Scripts to download or generate data
    │   ├── features       <- Scripts to turn raw data into features for modeling
    │   ├── models         <- Scripts to train models and then use trained models to make
    │   │                     predictions
    │   ├── pages          <- Contains your application views
    │   ├── style          <- Contains all style related code 
    │   ├── utils          <- This folder is for storing all utility functions, such as auth, 
    |   |                     theme, handleApiError, etc.
    │   ├── visualization  <- Scripts to create visualizations 
    |   └── widgets        <- Contains custom widgets 
    │
    ├── .env                        <- File for storing passwords
    ├── .gitignore                  <- Specifies intentionally untracked files to ignore
    ├── .pre-commit.config.yaml     <- Configuration file for the pre-commits
    ├── poetry.lock                 <- Autogenerated file for handling dependencies
    ├── pyproject.toml              <- Configuration of dependencies and project variables e.g. version
    └── README.md                   <- The top-level README for developers using this project.

为了实现动态更新，我们可以将上述内容修改为 Jinja 模板，使用 {% if %} 和 {% endif %} 语句：

Stuff before the directory diagram
{% if cookiecutter.include_gui_structure %}
    ├── assets             <- Folder for storing assets like images 
{%- endif %}
    ├── data               <- Folder for storing your data 
{%- if cookiecutter.use_sphinx_documentation %}
    ├── docs               <- A default Sphinx project; see sphinx-doc.org for details
{%- endif %}
{%- if cookiecutter.include_data_science_structure %}
    ├── models             <- Trained and serialized models, model predictions, or model summaries
{%- endif %}
    ├── notebooks          <- Jupyter notebooks
    |
    ├── src                <- Source code for use in this project
    │   ├── data           <- Scripts to download or generate data
{%- if cookiecutter.include_data_science_structure %}
    │   ├── features       <- Scripts to turn raw data into features for modeling
    │   ├── models         <- Scripts to train models and then use trained models to make
    │   │                     predictions
{%- endif %}
{%- if cookiecutter.include_gui_structure %}
    │   ├── pages          <- Contains your application views
    │   ├── style          <- Contains all style related code 
{%- endif %}
    │   ├── utils          <- This folder is for storing all utility functions, such as auth, 
    |   |                     theme, handleApiError, etc.
{%- if cookiecutter.include_data_science_structure %}
    │   ├── visualization  <- Scripts to create visualizations 
{%- endif %}
{%- if cookiecutter.include_gui_structure %}
    |   └── widgets        <- Contains custom widgets 
{%- endif %}
    │
    ├── .env                        <- File for storing passwords
    ├── .gitignore                  <- Specifies intentionally untracked files to ignore
{%- if cookiecutter.use_pre_commits %}
    ├── .pre-commit.config.yaml     <- Configuration file for the pre-commits
{%- endif %}
    ├── poetry.lock                 <- Autogenerated file for handling dependencies
    ├── pyproject.toml              <- Configuration of dependencies and project variables e.g. version
    └── README.md                   <- The top-level README for developers using this project.

Stuff after the folder diagram.

说明：

• {% if cookiecutter.variable_name %}: 如果 cookiecutter.variable_name 的值为真（例如 true），则包含 if 块内的内容。
• {%- endif %}: {%- 用于去除 Jinja 语句块前的空白字符，确保生成的 README.md 格式整洁，避免多余的空行。

通过这种方式，Cookiecutter 在生成项目时，会根据用户在 cookiecutter.json 中对 include_gui_structure、use_sphinx_documentation、include_data_science_structure 和 use_pre_commits 等变量的设置，自动渲染出正确的 README.md 文件内容。如果所有内容都可以在模板阶段处理，那么 post_gen_project.py 脚本将不再需要用于此目的。

为什么原始的 post_gen_project.py 脚本未能奏效？

原始的 Python 脚本尝试通过字符串比较来判断是否跳过某些行。问题出在 Jinja 模板引擎在将 cookiecutter 变量传递给 Python 脚本时，会将其转换为字符串。

考虑以下比较：

"{{ cookiecutter.use_pre_commits }}" == "false"

当 cookiecutter.use_pre_commits 在 cookiecutter.json 中设置为 false 时，Jinja 会将其渲染为 Python 脚本中的字符串 "False"。因此，上述比较实际上变成了：

"False" == "false"  # 结果为 False

由于 Python 中的字符串 "False" 和 "false" 是不相等的，所以条件判断始终为 False，导致预期的行未能被跳过。

修复 post_gen_project.py 中的逻辑（不推荐）

如果确实需要在 post_gen_project.py 中处理此类逻辑，必须确保比较的类型一致。

1. 字符串与字符串比较：

   "{{ cookiecutter.use_pre_commits }}" == "False"

   这里，cookiecutter.use_pre_commits 的值（例如 false）会被 Jinja 渲染成 Python 字符串 "False"。因此，需要将其与字符串 "False" 进行比较。

2. 布尔值与布尔值比较（推荐在 Python 脚本中）：

   {{ cookiecutter.use_pre_commits }} == False

   在这种情况下，Jinja 会直接将 cookiecutter.use_pre_commits 的布尔值（例如 false）作为 Python 的布尔值 False 传递给脚本。这样，比较就变成了 False == False，结果为 True，从而正确触发逻辑。

注意事项： 尽管可以通过上述方式修复 Python 脚本中的逻辑，但这种混合 Jinja 渲染和 Python 逻辑的方式容易出错，且可读性较差。Cookiecutter 的 JSON 配置、Jinja 模板语法和 Python 脚本使用不同的类型系统和语法，这增加了复杂性。因此，对于模板内容的条件生成，强烈建议优先使用 Jinja 模板自身的条件语句。

总结与最佳实践

• 优先使用 Jinja 模板的条件逻辑： 对于根据 Cookiecutter 变量动态生成或排除模板文件中的内容，最推荐的方法是直接在模板文件（如 README.md）中使用 Jinja 的 {% if %} 语句。这使得逻辑与内容紧密结合，易于理解和维护。
• 理解类型转换： 当 cookiecutter 变量通过 Jinja 传递给 Python 脚本时，其类型可能会发生变化（例如，布尔值 false 变为字符串 "False"）。在编写 post_gen_project.py 脚本时，务必注意这些类型转换，并确保进行类型一致的比较。
• 合理使用 post_gen_project.py： post_gen_project.py 脚本应主要用于执行那些不能通过简单模板渲染完成的复杂任务，例如：
  • 运行外部命令（如 git init）。
  • 执行文件系统操作（如创建额外的目录、移动文件）。
  • 进行复杂的字符串处理或文件内容修改，这些修改超出了 Jinja 模板的表达能力。
  • 生成日志或向用户提供反馈。

通过遵循这些原则，可以更有效地管理 Cookiecutter 项目的生成过程，确保 README.md 和其他项目文件能够根据用户选择的特性准确地动态更新。