🔧 Add direct dependencies file: requirements.in

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,38 +133,61 @@ 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
 
     # 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
 

dev-requirements.in

@@ -1 +1 @@
-mkdocs-translate
+pip-tools

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

requirements.txt

@@ -1,48 +1,132 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile
+#
 babel==2.16.0
+    # via mkdocs-material
 beautifulsoup4==4.12.3
+    # via mkdocs-exporter
 bracex==2.5.post1
+    # via wcmatch
 certifi==2024.8.30
+    # via requests
 charset-normalizer==3.4.0
+    # via requests
 click==8.1.7
+    # via mkdocs
 colorama==0.4.6
+    # via mkdocs-material
 ghp-import==2.1.0
+    # via mkdocs
 greenlet==3.0.3
+    # via playwright
 hjson==3.1.0
+    # via
+    #   mkdocs-macros-plugin
+    #   super-collections
 idna==3.10
-Jinja2==3.1.4
+    # via requests
+jinja2==3.1.4
+    # via
+    #   mkdocs
+    #   mkdocs-macros-plugin
+    #   mkdocs-material
 libsass==0.23.0
+    # via mkdocs-exporter
 lxml==5.3.0
-Markdown==3.7
-MarkupSafe==3.0.1
+    # via mkdocs-exporter
+markdown==3.7
+    # via
+    #   mkdocs
+    #   mkdocs-material
+    #   pymdown-extensions
+markupsafe==3.0.1
+    # via
+    #   jinja2
+    #   mkdocs
 mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
 mkdocs==1.6.1
+    # via
+    #   -r requirements.in
+    #   mkdocs-exclude
+    #   mkdocs-exporter
+    #   mkdocs-include-markdown-plugin
+    #   mkdocs-macros-plugin
+    #   mkdocs-material
+    #   mkdocs-open-in-new-tab
 mkdocs-exclude==1.0.2
+    # via -r requirements.in
 mkdocs-exporter==6.1.1
+    # via -r requirements.in
 mkdocs-get-deps==0.2.0
+    # via mkdocs
 mkdocs-include-markdown-plugin==6.2.2
+    # via -r requirements.in
 mkdocs-macros-plugin==1.3.5
+    # via -r requirements.in
 mkdocs-material==9.5.40
+    # via -r requirements.in
 mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
 mkdocs-open-in-new-tab==1.0.6
+    # via -r requirements.in
 packaging==24.1
+    # via
+    #   mkdocs
+    #   mkdocs-macros-plugin
 paginate==0.5.7
+    # via mkdocs-material
 pathspec==0.12.1
+    # via
+    #   mkdocs
+    #   mkdocs-macros-plugin
 platformdirs==4.3.6
+    # via mkdocs-get-deps
 playwright==1.47.0
+    # via mkdocs-exporter
 pyee==12.0.0
-Pygments==2.18.0
+    # via playwright
+pygments==2.18.0
+    # via mkdocs-material
 pymdown-extensions==10.11.2
+    # via mkdocs-material
 pypdf==5.0.1
+    # via mkdocs-exporter
 python-dateutil==2.9.0.post0
-PyYAML==6.0.2
-pyyaml_env_tag==0.1
+    # via
+    #   ghp-import
+    #   mkdocs-macros-plugin
+pyyaml==6.0.2
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+    #   mkdocs-macros-plugin
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+pyyaml-env-tag==0.1
+    # via mkdocs
 regex==2024.9.11
+    # via mkdocs-material
 requests==2.32.3
+    # via mkdocs-material
 six==1.16.0
+    # via python-dateutil
 soupsieve==2.6
-super_collections==0.5.3
+    # via beautifulsoup4
+super-collections==0.5.3
+    # via mkdocs-macros-plugin
 termcolor==2.5.0
-typing_extensions==4.12.2
+    # via mkdocs-macros-plugin
+typing-extensions==4.12.2
+    # via pyee
 urllib3==2.2.3
+    # via requests
 watchdog==5.0.3
+    # via mkdocs
 wcmatch==10.0
+    # via mkdocs-include-markdown-plugin