From a9cf5fa515c2b04db75b4ebfedbf7baee042cf41 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Fri, 10 May 2024 11:27:16 +0200 Subject: [PATCH 1/4] =?UTF-8?q?=F0=9F=93=8C=20Pin=20project's=20dependenci?= =?UTF-8?q?es?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Freeze sphinx-copybutton version number. - Normalize package names to use dashes (-) as separators between words in the package name. This is the canonical format for package names on PyPI. --- requirements.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/requirements.txt b/requirements.txt index 1188b0a5..a085f98e 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ sphinx==5.3.0 -sphinx_rtd_theme==1.2.0 -sphinx_copybutton -myst_parser==0.18.1 +sphinx-rtd-theme==1.2.0 +sphinx-copybutton==0.5.2 +myst-parser==0.18.1 From 1affae328ced395e4e3ca68fa70106eff3750d46 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Sun, 29 Sep 2024 17:05:06 +0200 Subject: [PATCH 2/4] =?UTF-8?q?=E2=9E=95=20Add=20pip-tools=20dependency?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The direct dependencies ("top level packages") must now be listed in `requirements.in. We should now use `pip-compile` to create `requirements.txt`. pip-compile ` pip-compile` reads `requirements.in` to generate `requirements.txt` with the pinned direct and indirect dependencies. The `pip-compile` program is part of the `pip-tools` package. We need to install it first: python -m pip install pip-tools IMPORTANT: Do not to add packages/dependencies directly into `requirements.txt` but in `requirements.in`. --- requirements.in | 4 +++ requirements.txt | 78 ++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 80 insertions(+), 2 deletions(-) create mode 100644 requirements.in diff --git a/requirements.in b/requirements.in new file mode 100644 index 00000000..ee8765d4 --- /dev/null +++ b/requirements.in @@ -0,0 +1,4 @@ +sphinx==5.3.0 +sphinx-copybutton==0.5.2 +sphinx-rtd-theme==1.2.0 +myst-parser==0.18.1 diff --git a/requirements.txt b/requirements.txt index a085f98e..3807a9de 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,78 @@ +# +# This file is autogenerated by pip-compile with Python 3.12 +# by the following command: +# +# pip-compile +# +alabaster==0.7.16 + # via sphinx +babel==2.16.0 + # via sphinx +certifi==2024.8.30 + # via requests +charset-normalizer==3.3.2 + # via requests +docutils==0.18.1 + # via + # myst-parser + # sphinx + # sphinx-rtd-theme +idna==3.10 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.4 + # via + # myst-parser + # sphinx +markdown-it-py==2.2.0 + # via + # mdit-py-plugins + # myst-parser +markupsafe==2.1.5 + # via jinja2 +mdit-py-plugins==0.3.5 + # via myst-parser +mdurl==0.1.2 + # via markdown-it-py +myst-parser==0.18.1 + # via -r requirements.in +packaging==24.1 + # via sphinx +pygments==2.18.0 + # via sphinx +pyyaml==6.0.2 + # via myst-parser +requests==2.32.3 + # via sphinx +snowballstemmer==2.2.0 + # via sphinx sphinx==5.3.0 -sphinx-rtd-theme==1.2.0 + # via + # -r requirements.in + # myst-parser + # sphinx-copybutton + # sphinx-rtd-theme + # sphinxcontrib-jquery sphinx-copybutton==0.5.2 -myst-parser==0.18.1 + # via -r requirements.in +sphinx-rtd-theme==1.2.0 + # via -r requirements.in +sphinxcontrib-applehelp==2.0.0 + # via sphinx +sphinxcontrib-devhelp==2.0.0 + # via sphinx +sphinxcontrib-htmlhelp==2.1.0 + # via sphinx +sphinxcontrib-jquery==4.1 + # via sphinx-rtd-theme +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==2.0.0 + # via sphinx +sphinxcontrib-serializinghtml==2.0.0 + # via sphinx +typing-extensions==4.12.2 + # via myst-parser +urllib3==2.2.3 + # via requests From 1070588d4cc4cb11a1baaeda1176a5a67d6d4ae3 Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Mon, 30 Sep 2024 18:17:56 +0200 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=94=A7=20Add=20a=20dependencies=20dev?= =?UTF-8?q?elopment=20file:=20dev-requirements.txt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Install the development dependencies before other dependencies: # First: Install dev dependencies python -m pip install -r dev-requirements.txt # Next: Install production dependencies/packages python -m pip install -r requirements.txt --- dev-requirements.txt | 1 + 1 file changed, 1 insertion(+) create mode 100644 dev-requirements.txt diff --git a/dev-requirements.txt b/dev-requirements.txt new file mode 100644 index 00000000..2c2a9f38 --- /dev/null +++ b/dev-requirements.txt @@ -0,0 +1 @@ +pip-tools From b2e802d8abf0da7f41d1f37702b339be002c011d Mon Sep 17 00:00:00 2001 From: Eric Bouchut Date: Wed, 30 Oct 2024 16:47:14 +0100 Subject: [PATCH 4/4] =?UTF-8?q?=F0=9F=93=9D=20Update=20README:=20Add=20how?= =?UTF-8?q?=20to=20use=20pip-compile=20to=20generate=20the=20dependencies?= =?UTF-8?q?=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update wording to use `package` instead of `plugin` --- README.md | 52 ++++++++++++++++++++++++++++++++------------ dev-requirements.txt | 24 ++++++++++++++++++++ 2 files changed, 62 insertions(+), 14 deletions(-) create mode 100644 dev-requirements.txt diff --git a/README.md b/README.md index fb638a8c..39c9ca93 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ Repository for [Trio documentation (under development)](https://docs.diy-trio.or ```shell cd trio-docs # where you cloned the trio-docs repository + python -m pip install -r dev-requirements.txt python -m pip install -r requirements.txt ``` @@ -132,17 +133,27 @@ git push -u origin add_FAQ_page This page displays a box saying you can create a Pull-Request for your branch. - Click the button to do so, then follow the instructions. -### Add a Plugin +### Add a Package -- Create a feature branch -- Add the pinned version of the new plugin to the **`requirements.in`** file +> [!NOTE] +> In this section, the terms Python **package** and **dependency** refer to the same thing. + +- **Create** a feature **branch** (aka. topic branch) + ```shell + git switch dev + git switch -c feature/add_dependency_XXX + ``` +- **Add** the pinned version of the new **package** to the **`requirements.in`** file ```shell MY_FAVORITE_EDITOR_HERE requirements.in - # Add the pinned version (i.e. plugin name + version) to `requirements.in - XXX_PLUGIN_NAME_HERE==XXX_PLUGIN_VERSION_HERE + # Add the pinned version of the package to `requirements.in + XXX_PACKAGE_NAME_HERE==XXX_PACKAGE_VERSION_HERE ``` - For example, add this line `mkdocs-exporter==6.1.1` to `requirements.in` + For example, to add the `mkdocs-exporter` package version `6.1.1`, I added the following line to the `requirements.in` file: + ```text + mkdocs-exporter==6.1.1 + ``` - Generate **`requirements.txt`** ```shell cd trio-docs @@ -150,20 +161,33 @@ git push -u origin add_FAQ_page # IMPORTANT: The project's virtual environment MUST be activated first source venv/bin/activate - # Remove already installed plugins - python -m pip freeze --exclude-editable | xargs python -m pip uninstall -y + # Remove the already installed packages in case you need to start from a blank slate + # python -m pip freeze --exclude-editable | xargs python -m pip uninstall -y - # Install the dependencies listed in `requirements.in` - # This installs the indirect dependencies these plugins depend upon. + # Install the development packages + # (among which `pip-tools` that contains `pip-compile`) + pip install -r dev-requirements.txt + + # Install the direct dependencies (listed in `requirements.in` + # This also installs the indirect dependencies these packages depend upon. pip install -r requirements.in - # Generate `requirements.txt` with both direct AND indirect dependencies - pip freeze > requirements.txt + # Add code/doc using this package and test until it is ready. + + # Generate the `requirements.txt` file from `requirements.in` + pip-compile - # Commit the changes (where XXX denotes the plugin name) + # Commit the changes (where XXX denotes the package name) git add requirements.in requirements.txt - git commit -m "➕ Add dependency XXX" + git commit -m "➕ Add dependency: XXX" + + # Push your feature branch to your `origin` repository + git push -u origin feature/add_dependency_XXX ``` +- [**Create a Pull Request**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) with your changes: + - Open your clone repository of `trio-docs` on *GitHub* (`https://github.com/YOUR_USERNAME/trio-docs`) + - Click the `Pull Requests` tab + - Click "`Compare & pull request`" in the yellow banner next to your branch name ## Tips & Tricks diff --git a/dev-requirements.txt b/dev-requirements.txt new file mode 100644 index 00000000..76bfa83b --- /dev/null +++ b/dev-requirements.txt @@ -0,0 +1,24 @@ +# +# This file is autogenerated by pip-compile with Python 3.12 +# by the following command: +# +# pip-compile --output-file=dev-requirements.txt dev-requirements.in +# +build==1.2.2.post1 + # via pip-tools +click==8.1.7 + # via pip-tools +packaging==24.1 + # via build +pip-tools==7.4.1 + # via -r dev-requirements.in +pyproject-hooks==1.2.0 + # via + # build + # pip-tools +wheel==0.44.0 + # via pip-tools + +# The following packages are considered to be unsafe in a requirements file: +# pip +# setuptools