From 2cc5a0e888260dd3c771d0f24699be66dd983542 Mon Sep 17 00:00:00 2001
From: Mhenwa <1986535482@qq.com>
Date: Sat, 22 Jun 2024 17:48:01 +0800
Subject: [PATCH] feat: added instructions for use

---
 README.md                         | 24 ++++++++++++++++++++++++
 docs/images/README.md             |  1 +
 integrated_tests/README.md        |  1 +
 integrated_tests/sample/README.md |  1 +
 project_name/README.md            |  1 +
 project_name/__main__.py          |  4 ++++
 project_name/scripts/README.md    |  1 +
 project_name/settings.yml         |  1 +
 pyproject.toml                    |  3 +++
 tests/README.md                   |  1 +
 tests/sample/README.md            |  1 +
 11 files changed, 39 insertions(+)
 create mode 100644 docs/images/README.md
 create mode 100644 integrated_tests/README.md
 create mode 100644 integrated_tests/sample/README.md
 create mode 100644 project_name/README.md
 create mode 100644 project_name/scripts/README.md
 create mode 100644 tests/README.md
 create mode 100644 tests/sample/README.md

diff --git a/README.md b/README.md
index 4d37aba..986d198 100644
--- a/README.md
+++ b/README.md
@@ -30,3 +30,27 @@
    ```shell
    pdm run python project_name/__main__.py
    ```
+
+## 示例内容说明
+
+- 针对场景：用以直接运行的`Python`项目，除了`Django`和`Python库`有各自的模板以外，一般情况都可以用。
+
+- 用法：创建`Github`仓库时可以选择为模板，已经创建仓库的可以手动参照调整。
+
+- 需要注意修改的：`pyproject.toml` 和 `README` 中的名称和描述；`project_name` 文件夹重命名为项目名称或史诗名称
+
+- 包含内容：`dynaconf` 配置（`project_name/config.py`）、日志配置（`project_name/__main__.py` 与 `settings.yml`）、`pdm` 配置（`pyproject.toml`、`pdm.lock`，默认依赖 `dynaconf、pytest`）、文档结构（`README`、`CHANGELOG`、`docs`（用户文档））、代码目录结构（`tests`（单元测试）、`integrated_tests`（集成测试））、`.gitignore`
+
+- 备注：
+
+   - `__main__.py` 是其目录下所有代码的唯一统一入口（如有需要可改名），如有其它需单独运行的简单脚本，在项目根目录下创建 `scripts` 文件夹；如有多个不能一起完成的交付目标（里程碑），在项目根目录下新创建文件夹及其自己的 `__main__.py` 等文件
+
+   - 如需跨一级目录（一级目录即项目根目录的下一级）`import` 代码，将`pyproject.toml` 中的 `[tool.pdm] distribution` 改为 `true`，重新执行 `pdm install` 后即可从任意一级目录开始 `import`
+
+   - 要指定环境时，在 `settings.yml` 同目录下创建 `.env` 文件以指定环境，内容如 `DYNACONF_STAGE=prod`
+
+   - 涉及敏感配置时（各类密码密钥、用户名、我们的服务器地址、IP等），在 `settings.yml` 同目录下创建 `.secrets.yml` 文件（`.gitignore` 末尾已添加 `.secrets.*`）以放置敏感配置
+
+   - 有测试数据文件要放时，在 `tests` 或 `integrated_tests` 目录下创建 `sample` 文件夹放置
+
+   - 用户文档有图片时，在 `docs` 目录下创建 `images` 文件夹放置
diff --git a/docs/images/README.md b/docs/images/README.md
new file mode 100644
index 0000000..290e7d2
--- /dev/null
+++ b/docs/images/README.md
@@ -0,0 +1 @@
+# 用户文档的图片放置于此
\ No newline at end of file
diff --git a/integrated_tests/README.md b/integrated_tests/README.md
new file mode 100644
index 0000000..30dc4dd
--- /dev/null
+++ b/integrated_tests/README.md
@@ -0,0 +1 @@
+# 集成测试代码
\ No newline at end of file
diff --git a/integrated_tests/sample/README.md b/integrated_tests/sample/README.md
new file mode 100644
index 0000000..ff32107
--- /dev/null
+++ b/integrated_tests/sample/README.md
@@ -0,0 +1 @@
+# 在此文件夹下放置集成测试测试数据文件
\ No newline at end of file
diff --git a/project_name/README.md b/project_name/README.md
new file mode 100644
index 0000000..97dc371
--- /dev/null
+++ b/project_name/README.md
@@ -0,0 +1 @@
+# 项目代码源代码
\ No newline at end of file
diff --git a/project_name/__main__.py b/project_name/__main__.py
index 834921f..ca81a25 100644
--- a/project_name/__main__.py
+++ b/project_name/__main__.py
@@ -1,6 +1,10 @@
 # -*- coding: utf-8 -*-
 """
 程序启动入口
+此文件是该目录下所有代码的唯一统一入口（如有需要可改名）
+如有其它需单独运行的简单脚本，在项目根目录下创建 `scripts` 文件夹
+如有多个不能一起完成的交付目标（里程碑）
+在项目根目录下新创建文件夹及其自己的 `__main__.py` 等文件
 """
 import logging
 
diff --git a/project_name/scripts/README.md b/project_name/scripts/README.md
new file mode 100644
index 0000000..f818880
--- /dev/null
+++ b/project_name/scripts/README.md
@@ -0,0 +1 @@
+# 在此处放置其它需单独运行的简单脚本
\ No newline at end of file
diff --git a/project_name/settings.yml b/project_name/settings.yml
index de341d3..c7056a2 100644
--- a/project_name/settings.yml
+++ b/project_name/settings.yml
@@ -6,3 +6,4 @@ default:
 dev:
 test:
 prod:
+
diff --git a/pyproject.toml b/pyproject.toml
index b946963..1d5c07a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -23,6 +23,9 @@ dependencies = [
 file = "README.md"
 content-type = "text/markdown"
 
+# 如需跨一级目录（一级目录即项目根目录的下一级）`import` 代码，
+# 将此处的 distribution 改为 true
+# 重新执行 pdm install 后即可从任意一级目录开始 import
 [tool.pdm]
 distribution = false
 
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..e6276b2
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1 @@
+# 单元测试代码
\ No newline at end of file
diff --git a/tests/sample/README.md b/tests/sample/README.md
new file mode 100644
index 0000000..b68ad5f
--- /dev/null
+++ b/tests/sample/README.md
@@ -0,0 +1 @@
+# 在此文件夹下放置单元测试测试数据文件
\ No newline at end of file