[Docutils-develop] [docutils:patches] #186 Modernise packaging

[Günter M. <mi...@us...>]

Thank you for the elaborated patch set. Please be patient with our hesitation to apply it as-is.

Although officially still in Beta stage (version number <1.0), Docutils is  widely used as if it were stable and we try to minimise the impact of changes on users.

Installation should be possible without  dependencies other than stock Python and its standard library. There is an exception with setup.py requiring "setuptools", but currently it's also possible to get Docutils running by placing a `*.pth` file in the Python path and symlinks for the front-ends in the binary path (`/usr/local/bin/rst2html5 -> /usr/local/src/Docutils/docutils/tools/rst2html5.py`, say).

Switching to static metadata should be possible without violating this condition. Renaming setup.py to pyproject.toml before applying the changes to make it a `toml` file would allow keeping the  classifiers  in the version history.

The "longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points" comes as a suprise to me.
I see the potential benefit for Windows users,  OTOH, I'd like to keep the front-ends as executable files for "hand installation" as well as templates for custom, home made front-ends.
I wonder if we could eat the cake and have it by moving the `tools/` directory inside the package (maybe renaming it to `cli/`) and modifying the front-end tools to provide an entry function that is executed `if name == '__main__`.

A name change for the frontend tools is an API change that requires an advance warning in the RELEASE-NOTES (note that, e.g., Debian already drops the `*.py` extension from the front-end tools). If implemented via an "entry point", the command name `docutils-cli` may also be simplified to `docutils`.
Once we are at it, it may be worth discussing which front-end tools should be provided. The generic `docutils-cli` could obsolete some or all of the `rst2*.py` scripts, but it is new and not yet reviewed/endorsed by Docutils main author David Goodger.
Also, regular Docutils users and developers benefit from dedicated tools (and TAB-expansion after typing `rst2`) while users installing Docutils only because it is required by some other package may prefer less "noise" in the binary path.


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Mon Jan 03, 2022 03:50 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.