Merge pull request #104 from Undertone0809/zeeland/optimize-readme

docs: optimize README
Undertone0809 · Apr 4, 2024 · 52be9a9 · 52be9a9
2 parents 97e720a + 5e2833e
commit 52be9a9
Show file tree

Hide file tree

Showing 5 changed files with 168 additions and 160 deletions.
diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@ Your next Python package needs a bleeding-edge project structure.
 
 ```bash
 pip install cookiecutter
-cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.9
+cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.10
 ```
 
 > All you need is the latest version of cookiecutter 😉
@@ -72,7 +72,7 @@ pip install -U cookiecutter
 then go to a directory where you want to create your project and run:
 
 ```bash
-cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.9
+cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.10
 ```
 
 ### Input variables

diff --git a/README_zh.md b/README_zh.md
@@ -21,7 +21,7 @@
 
 ```bash
 pip install cookiecutter
-cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.9
+cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.10
 ```
 
 > 你所需要的只是最新版本的 cookiecutter 😉
@@ -70,7 +70,7 @@ pip install -U cookiecutter
 然后转到你想创建项目的目录并运行：
 
 ```bash
-cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.9
+cookiecutter gh:Undertone0809/python-package-template --checkout v1.1.10
 ```
 
 ### 输入变量

diff --git a/pyproject.toml b/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "python-package-template"
-version = "1.1.9"
+version = "1.1.10"
 description = "Cookiecutter template for Python cli/packages"
 readme = "README.md"
 authors = ["Zeeland <[email protected]>"]

diff --git a/...cutter.project_name.lower().replace(' ', '_').replace('-', '_') }}/DELETE_ME.md b/...cutter.project_name.lower().replace(' ', '_').replace('-', '_') }}/DELETE_ME.md
@@ -0,0 +1,155 @@
+# Guide for {{ cookiecutter.github_name }}, the owners of the repository 😀
+
+**👉 You can delete this file after reading and operating the instructions.**
+
+## 1. Very first steps
+
+### 1.1. Initialize your code
+
+1. Initialize `git` inside your repo:
+
+```bash
+cd {{ cookiecutter.project_name }} && git init
+```
+
+2. If you don't have `Poetry`. 
+
+Conda environment is is recommended.
+
+```bash
+conda create -n {{ cookiecutter.project_name }} python==3.10
+```
+
+Please activate python of current project and install run:
+
+```bash
+conda activate {{ cookiecutter.project_name }}
+pip install poetry
+```
+
+3. Initialize poetry and `pre-commit` hooks:
+
+```bash
+make install
+```
+
+If you obtain a timeout error when installing, you can try to append an image source config in `poetry.toml`. The following example is tsinghua image source.
+
+```toml
+[[tool.poetry.source]]
+name = "tsinghua"
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+priority = "default"
+```
+
+4. Run the codestyle to polish your code:
+
+```bash
+make polish-codestyle
+```
+
+5. Upload initial code to GitHub:
+
+```bash
+git add .
+git commit -m ":tada: Initial commit"
+git branch -M main
+git remote add origin https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}.git
+git push -u origin main
+```
+
+### 1.2. Set up bots
+
+When you create this repository, you have already set up the following bots, so that you can use it in relevant GitHub repository.
+
+- [Dependabot](https://docs.github.com/en/github/administering-a-repository/enabling-and-disabling-version-updates#enabling-github-dependabot-version-updates): will create a pull request to update the dependencies. You can also enable it to automatically merge the pull request after the CI/CD passes. You can configure it in `.github/dependabot.yml`.
+- [Stale bot](https://github.com/apps/stale): Automatically closes abandoned issues after a period of inactivity. You can configure it in `.github/.stale.yml`.
+- [first-interaction](./.github/workflows/greetings.yml): will comment on the first issue or pull request from a new contributor. You can configure it in `.github/workflows/greetings.yml`.
+
+> ❗ **first-interaction** requires `pull_requests:write`, but by default `GITHUB_TOKEN` has this value set to read-only. You need to do the following to enable it:
+> - Go to the repository settings
+> - Open the "Actions" tab
+> - Click on "Read and write permissions" and enable "Actions: Read and write permissions"
+> ![img.png](assets/images/img_1.png)
+
+
+### 1.3. Poetry
+
+This project use Poetry to manage dependencies. Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. 
+
+Want to know more about Poetry? Check [its documentation](https://python-poetry.org/docs/).
+
+<details>
+<summary>Details about Poetry</summary>
+<p>
+
+Poetry's [commands](https://python-poetry.org/docs/cli/#commands) are very intuitive and easy to learn, like:
+
+- `poetry add numpy@latest` add a new dependency.
+- `poetry run pytest` run tests.
+- `poetry publish --build` publish your package.
+
+etc
+</p>
+</details>
+
+### 1.4. Building and releasing your package (Optional)
+
+You can build and release your package to PyPI. Building a new version of the application contains steps:
+
+- Bump the version of your package `poetry version <version>`. You can pass the new version explicitly, or a rule such as `major`, `minor`, or `patch`. For more details, refer to the [Semantic Versions](https://semver.org/) standard.
+- Make a commit to `GitHub`.
+- Create a `GitHub release`.
+- And... publish 🙂 `poetry publish --build`
+
+## 🎯 2. What's next
+
+Well, that's up to you 💪🏻. I can only recommend the packages and articles that helped me.
+
+- [`Typer`](https://github.com/tiangolo/typer) is great for creating CLI applications.
+- [`Rich`](https://github.com/willmcgugan/rich) makes it easy to add beautiful formatting in the terminal.
+- [`Pydantic`](https://github.com/samuelcolvin/pydantic/) – data validation and settings management using Python type hinting.
+- [`Loguru`](https://github.com/Delgan/loguru) makes logging (stupidly) simple.
+- [`tqdm`](https://github.com/tqdm/tqdm) – fast, extensible progress bar for Python and CLI.
+- [`IceCream`](https://github.com/gruns/icecream) is a little library for sweet and creamy debugging.
+- [`orjson`](https://github.com/ijl/orjson) – ultra fast JSON parsing library.
+- [`Returns`](https://github.com/dry-python/returns) makes you function's output meaningful, typed, and safe!
+- [`Hydra`](https://github.com/facebookresearch/hydra) is a framework for elegantly configuring complex applications.
+- [`FastAPI`](https://github.com/tiangolo/fastapi) is a type-driven asynchronous web framework.
+
+Articles:
+
+- [Open Source Guides](https://opensource.guide/).
+- [A handy guide to financial support for open source](https://github.com/nayafia/lemonade-stand)
+- [GitHub Actions Documentation](https://help.github.com/en/actions).
+- Maybe you would like to add [gitmoji](https://gitmoji.carloscuesta.me/) to commit names. This is really funny. 😄
+
+## 🚀 3. Features
+
+### 3.1. Development features
+
+- Supports for `Python 3.8` and higher.
+- [`Poetry`](https://python-poetry.org/) as the dependencies manager. See configuration in [`pyproject.toml`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/pyproject.toml) and [`setup.cfg`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/setup.cfg).
+- Faster formatter tool, automatic codestyle with [`ruff`](https://github.com/astral-sh/ruff) to replace [`black`](https://github.com/psf/black), [`isort`](https://github.com/timothycrosley/isort) and [`pyupgrade`](https://github.com/asottile/pyupgrade).
+- Ready-to-use [`pre-commit`](https://pre-commit.com/) hooks with code-formatting.
+- Type checks with  [`ruff`](https://github.com/astral-sh/ruff); docstring checks with [`darglint`](https://github.com/terrencepreilly/darglint); security checks with [`safety`](https://github.com/pyupio/safety) and [`bandit`](https://github.com/PyCQA/bandit)
+- Testing with [`pytest`](https://docs.pytest.org/en/latest/).
+- Ready-to-use [`.editorconfig`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.editorconfig), [`.dockerignore`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.dockerignore), and [`.gitignore`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.gitignore). You don't have to worry about those things.
+
+### 3.2. Deployment features
+
+- `GitHub` integration: issue and pr templates.
+- `Github Actions` with predefined [build workflow](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/workflows/build.yml) as the default CI/CD.
+- Everything is already set up for security checks, codestyle checks, code formatting, testing, linting, docker builds, etc with [`Makefile`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/Makefile#L89). More details in [makefile-usage](#makefile-usage).
+- [Dockerfile](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/docker/Dockerfile) for your package.
+- Always up-to-date dependencies with [`@dependabot`](https://dependabot.com/). You will only [enable it](https://docs.github.com/en/github/administering-a-repository/enabling-and-disabling-version-updates#enabling-github-dependabot-version-updates).
+- Automatic drafts of new releases with [`Release Drafter`](https://github.com/marketplace/actions/release-drafter). You may see the list of labels in [`release-drafter.yml`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/release-drafter.yml). Works perfectly with [Semantic Versions](https://semver.org/) specification.
+
+### 3.3. Open source community features
+
+- Ready-to-use [Pull Requests templates](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/PULL_REQUEST_TEMPLATE.md) and several [Issue templates](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/tree/main/.github/ISSUE_TEMPLATE).
+- Files such as: `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` are generated automatically.
+- [`Stale bot`](https://github.com/apps/stale) that closes abandoned issues after a period of inactivity. (You will only [need to setup free plan](https://github.com/marketplace/stale)). Configuration is [here](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/.stale.yml).
+- [Semantic Versions](https://semver.org/) specification with [`Release Drafter`](https://github.com/marketplace/actions/release-drafter).
+
+**👉 Remember delete this file after reading and operating the instructions.**
diff --git a/...kiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}/README.md b/...kiecutter.project_name.lower().replace(' ', '_').replace('-', '_') }}/README.md
@@ -1,3 +1,9 @@
+# Hey, Look at me! 👇
+
+**Please delete this part after you read it.**
+
+If you are first create this repository, please read [DELETE_ME.md](./DELETE_ME.md) to get started.
+
 # {{ cookiecutter.project_name }}
 
 <div align="center">
@@ -17,160 +23,7 @@
 
 </div>
 
-## Very first steps
-
-### Initialize your code
-
-1. Initialize `git` inside your repo:
-
-```bash
-cd {{ cookiecutter.project_name }} && git init
-```
-
-2. If you don't have `Poetry`. 
-
-Conda environment is is recommended.
-
-```bash
-conda create -n {{ cookiecutter.project_name }} python==3.10
-```
-
-Please activate python of current project and install run:
-
-```bash
-conda activate {{ cookiecutter.project_name }}
-pip install poetry
-```
-
-3. Initialize poetry and `pre-commit` hooks:
-
-```bash
-make install
-```
-
-If you obtain a timeout error when installing, you can try to append an image source config in `poetry.toml`. The following example is tsinghua image source.
-
-```toml
-[[tool.poetry.source]]
-name = "tsinghua"
-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
-priority = "default"
-```
-
-4. Run the codestyle to polish your code:
-
-```bash
-make polish-codestyle
-```
-
-5. Upload initial code to GitHub:
-
-```bash
-git add .
-git commit -m ":tada: Initial commit"
-git branch -M main
-git remote add origin https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}.git
-git push -u origin main
-```
-
-### Set up bots
-
-When you create this repository, you have already set up the following bots, you can use it in relevant GitHub repository.
-
-- Set up [Dependabot](https://docs.github.com/en/github/administering-a-repository/enabling-and-disabling-version-updates#enabling-github-dependabot-version-updates) to ensure you have the latest dependencies.
-
-> Dependabot will create a pull request to update the dependencies. You can also enable it to automatically merge the pull request after the CI/CD passes. Click [here](https://github.com/Undertone0809/python-package-template/issues/95) to see the detail. 
-
-- Set up [Stale bot](https://github.com/apps/stale) for automatic issue closing.
-- Set up [first-interaction](./.github/workflows/greetings.yml) to welcome new contributors.
-
-> ❗ **first-interaction** requires `pull_requests:write`, but by default `GITHUB_TOKEN` has this value set to read-only. You need to do the following to enable it:
-> - Go to the repository settings
-> - Open the "Actions" tab
-> - Click on "Read and write permissions" and enable "Actions: Read and write permissions"
-> ![img.png](assets/images/img_1.png)
-
-
-### Poetry
-
-Want to know more about Poetry? Check [its documentation](https://python-poetry.org/docs/).
-
-<details>
-<summary>Details about Poetry</summary>
-<p>
-
-Poetry's [commands](https://python-poetry.org/docs/cli/#commands) are very intuitive and easy to learn, like:
-
-- `poetry add numpy@latest`
-- `poetry run pytest`
-- `poetry publish --build`
-
-etc
-</p>
-</details>
-
-### Building and releasing your package
-
-Building a new version of the application contains steps:
-
-- Bump the version of your package `poetry version <version>`. You can pass the new version explicitly, or a rule such as `major`, `minor`, or `patch`. For more details, refer to the [Semantic Versions](https://semver.org/) standard.
-- Make a commit to `GitHub`.
-- Create a `GitHub release`.
-- And... publish 🙂 `poetry publish --build`
-
-## 🎯 What's next
-
-Well, that's up to you 💪🏻. I can only recommend the packages and articles that helped me.
-
-- [`Typer`](https://github.com/tiangolo/typer) is great for creating CLI applications.
-- [`Rich`](https://github.com/willmcgugan/rich) makes it easy to add beautiful formatting in the terminal.
-- [`Pydantic`](https://github.com/samuelcolvin/pydantic/) – data validation and settings management using Python type hinting.
-- [`Loguru`](https://github.com/Delgan/loguru) makes logging (stupidly) simple.
-- [`tqdm`](https://github.com/tqdm/tqdm) – fast, extensible progress bar for Python and CLI.
-- [`IceCream`](https://github.com/gruns/icecream) is a little library for sweet and creamy debugging.
-- [`orjson`](https://github.com/ijl/orjson) – ultra fast JSON parsing library.
-- [`Returns`](https://github.com/dry-python/returns) makes you function's output meaningful, typed, and safe!
-- [`Hydra`](https://github.com/facebookresearch/hydra) is a framework for elegantly configuring complex applications.
-- [`FastAPI`](https://github.com/tiangolo/fastapi) is a type-driven asynchronous web framework.
-
-Articles:
-
-- [Open Source Guides](https://opensource.guide/).
-- [A handy guide to financial support for open source](https://github.com/nayafia/lemonade-stand)
-- [GitHub Actions Documentation](https://help.github.com/en/actions).
-- Maybe you would like to add [gitmoji](https://gitmoji.carloscuesta.me/) to commit names. This is really funny. 😄
-
-## 🚀 Features
-
-### Development features
-
-- Supports for `Python {{ cookiecutter.minimal_python_version }}` and higher.
-- [`Poetry`](https://python-poetry.org/) as the dependencies manager. See configuration in [`pyproject.toml`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/pyproject.toml) and [`setup.cfg`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/setup.cfg).
-- Faster formatter tool, automatic codestyle with [`ruff`](https://github.com/astral-sh/ruff) to replace [`black`](https://github.com/psf/black), [`isort`](https://github.com/timothycrosley/isort) and [`pyupgrade`](https://github.com/asottile/pyupgrade).
-- Ready-to-use [`pre-commit`](https://pre-commit.com/) hooks with code-formatting.
-- Type checks with  [`ruff`](https://github.com/astral-sh/ruff); docstring checks with [`darglint`](https://github.com/terrencepreilly/darglint); security checks with [`safety`](https://github.com/pyupio/safety) and [`bandit`](https://github.com/PyCQA/bandit)
-- Testing with [`pytest`](https://docs.pytest.org/en/latest/).
-- Ready-to-use [`.editorconfig`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.editorconfig), [`.dockerignore`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.dockerignore), and [`.gitignore`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.gitignore). You don't have to worry about those things.
-
-### Deployment features
-
-- `GitHub` integration: issue and pr templates.
-- `Github Actions` with predefined [build workflow](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/workflows/build.yml) as the default CI/CD.
-- Everything is already set up for security checks, codestyle checks, code formatting, testing, linting, docker builds, etc with [`Makefile`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/Makefile#L89). More details in [makefile-usage](#makefile-usage).
-- [Dockerfile](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/docker/Dockerfile) for your package.
-- Always up-to-date dependencies with [`@dependabot`](https://dependabot.com/). You will only [enable it](https://docs.github.com/en/github/administering-a-repository/enabling-and-disabling-version-updates#enabling-github-dependabot-version-updates).
-- Automatic drafts of new releases with [`Release Drafter`](https://github.com/marketplace/actions/release-drafter). You may see the list of labels in [`release-drafter.yml`](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/release-drafter.yml). Works perfectly with [Semantic Versions](https://semver.org/) specification.
-
-### Open source community features
-
-- Ready-to-use [Pull Requests templates](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/PULL_REQUEST_TEMPLATE.md) and several [Issue templates](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/tree/main/.github/ISSUE_TEMPLATE).
-- Files such as: `LICENSE`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` are generated automatically.
-- [`Stale bot`](https://github.com/apps/stale) that closes abandoned issues after a period of inactivity. (You will only [need to setup free plan](https://github.com/marketplace/stale)). Configuration is [here](https://github.com/{{ cookiecutter.github_name }}/{{ cookiecutter.project_name }}/blob/main/.github/.stale.yml).
-- [Semantic Versions](https://semver.org/) specification with [`Release Drafter`](https://github.com/marketplace/actions/release-drafter).
-
-## Installation locally
-
-> If you want to push your code to github repo, you can delete upper parts from [Very first steps](#very-first-steps) to [Open source community features](#open-source-community-features), [Installation Locally](#installation-locally) is for user.
+## Quick start
 
 Conda package manager is recommended. Create a conda environment.
 
@@ -203,7 +56,7 @@ poetry run {{ cookiecutter.project_name }} --help
 
 
 <details>
-<summary>1. Install all dependencies and pre-commit hooks</summary>
+<summary>Install all dependencies and pre-commit hooks</summary>
 <p>
 
 Install requirements: