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

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,7 +39,50 @@ 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`
+
+[^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).
+
+```
+[project.scripts]
+foo = "my_package.some_module:main_func"
+bar = "other_module:some_func"
+
+[project.gui-scripts]
+baz = "my_package_gui:start_func"
+```
+
+In this case `foo` and `bar` (and `baz` on Windows), e. g. their corresponding entry point functions, would be available as "applications" to pipx after installing the above example package.
+
+
+If you wish to provide documentation via `man` pages on UNIX-like systems then these can be added via a `tool.setuptools.data-files` section in `pyproject.toml`:
+
+```
+[tool.setuptools.data-files]
+"share/man/man1" = [ "manpage.1",]
+```
+
+In this case the manual page `manpage.1` could be accessed by the user after installing the above example package.
+
+Note that 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.
+
+Whilst `pyproject.toml` is preferred, the legacy `setup.cfg` file can be also be used:
+
+```
+[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
+
+```
+
+as can `setup.py`:
 
 ```
 setup(
@@ -52,28 +95,11 @@ setup(
         'gui_scripts': [
             'baz = my_package_gui:start_func',
         ]
-    }
-)
-```
-
-In this case `main_func` and `some_func` would be available to pipx after installing the above example package.
-
-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.
-
-```
-setup(
-    # other arguments here...
+    },
     data_files=[('share/man/man1', ['manpage.1'])]
 )
 ```
 
-In this case the manual page `manpage.1` would be available to pipx after installing the above example package.
-
-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,7 @@ nav:
 
 markdown_extensions:
   - markdown_gfm_admonition  # GitHub's admonition (alert) syntax
+  - footnotes
 
 plugins:
   - search: