GH1229 Update how-pipx-works documentation to include pyproject.toml (#…

…1274)

* Updated how-pipx-works documentation to include pyproject.toml, added changelog entry

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update docs/how-pipx-works.md

Co-authored-by: chrysle <fritzihab@posteo.de>

* Update docs/how-pipx-works.md

Co-authored-by: chrysle <fritzihab@posteo.de>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update docs/how-pipx-works.md

Co-authored-by: chrysle <fritzihab@posteo.de>

* Add footnotes to mkdocs.yml and update text to include setup.cfg

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Making the data-files warning an "admonition"

* Add tabbed code examples

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: chrysle <fritzihab@posteo.de>

changelog.d/1229.doc.md

@@ -0,0 +1 @@
+Update the docs for package developers on the use of configuration using pyproject.toml

docs/how-pipx-works.md

@@ -39,41 +39,67 @@ If you are a developer and want to be able to run
 pipx install MY_PACKAGE
 ```
 
-make sure you include an `entry_points` section in your `setup.py` file.
+make sure you include `scripts` and, optionally for Windows GUI applications `gui-scripts`, sections under your main table[^1] in `pyproject.toml` or their legacy equivalents for `setup.cfg` and `setup.py`.
 
-```
-setup(
-    # other arguments here...
-    entry_points={
-        'console_scripts': [
-            'foo = my_package.some_module:main_func',
-            'bar = other_module:some_func',
-        ],
-        'gui_scripts': [
-            'baz = my_package_gui:start_func',
-        ]
-    }
-)
-```
+[^1]: This is often the `[project]` table, but might also be differently named. Read more in the [PyPUG](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#writing-your-pyproject-toml).
 
-In this case `main_func` and `some_func` would be available to pipx after installing the above example package.
+=== "pyproject.toml"
 
-To install manual pages, which can be viewed with the `man` command on operating systems which have this command,
-include a
-[`data_files` section](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#data-files)
-in your `setup.py` file.
+    ```ini
+    [project.scripts]
+    foo = "my_package.some_module:main_func"
+    bar = "other_module:some_func"
 
-```
-setup(
-    # other arguments here...
-    data_files=[('share/man/man1', ['manpage.1'])]
-)
-```
+    [project.gui-scripts]
+    baz = "my_package_gui:start_func"
+
+    [tool.setuptools.data-files]
+    "share/man/man1" = [ "manpage.1",]
+    ```
+
+=== "setup.cfg"
+
+    ```ini
+    [options.entry_points]
+    console_scripts =
+        foo = my_package.some_module:main_func
+        bar = other_module:some_func
+    gui_scripts =
+        baz = my_package_gui:start_func
+
+    [options.data_files]
+    share/man/man1 =
+        manpage.1
+    ```
+
+=== "setup.py"
+
+    ```python
+    setup(
+        # other arguments here...
+        entry_points={
+            'console_scripts': [
+                'foo = my_package.some_module:main_func',
+                'bar = other_module:some_func',
+            ],
+            'gui_scripts': [
+                'baz = my_package_gui:start_func',
+            ]
+        },
+        data_files=[('share/man/man1', ['manpage.1'])]
+    )
+    ```
+
+In this case `foo` and `bar` (and `baz` on Windows) would be available as "applications" to pipx after installing the above example package, invoking their corresponding entry point functions.
+
+If you wish to provide documentation via `man` pages on UNIX-like systems then these can be added via a `data-files` keyword.
+
+In this case the manual page `manpage.1` could be accessed by the user after installing the above example package.
 
-In this case the manual page `manpage.1` would be available to pipx after installing the above example package.
+> [!WARNING]
+>
+> The `data-files` keyword is "discouraged" in the [setuptools documentation](https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html#setuptools-specific-configuration) but there is no alternative if `man` pages are a requirement.
 
-For a real-world example, see [pycowsay](https://github.com/cs01/pycowsay/blob/master/setup.py)'s `setup.py` source
-code.
+For a real-world example, see [pycowsay](https://github.com/cs01/pycowsay/blob/master/setup.py)'s `setup.py` source code.
 
-You can read more about entry points
-[here](https://setuptools.pypa.io/en/latest/userguide/quickstart.html#entry-points-and-automatic-script-creation).
+You can read more about entry points [here](https://setuptools.pypa.io/en/latest/userguide/quickstart.html#entry-points-and-automatic-script-creation).

mkdocs.yml

@@ -40,6 +40,10 @@ nav:
 
 markdown_extensions:
   - markdown_gfm_admonition  # GitHub's admonition (alert) syntax
+  - footnotes
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
 
 plugins:
   - search: