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

[Adam T. <aa-...@us...>]

> What I have in mind is a "manual install" 

Ahh, yes then that will continue to work -- sorry, I had thought you meant using some tool in Python's stdlib. 

> Names and arguments of the commands ... are part of Docutils' public API (cf. PEP 387).

I agree. My proposal isn't to remove them with no recourse, but to deprecate over a period of time, clearly marking identical drop-in commands at runtime to affected users. Yes we cannot know how many people would be affected with local random scripts, but it is a two-second change. 

Many users will also run with old or pinned versions of Docutils, and part of updating is seeing the changelog. If Debian or other redistributors already make changes, they could decide to keep shell aliases from `rst2*` to the new `docutils-cli` based invocations. 

> "entry point" for the benefit of Windows users seams feasible.

Entrypoints aren't just for the benefits of Windows users -- they are a standards based tool, whereas copying files from a directory straight onto PATH isn't -- setuptools just has that feature as an accident of history.

> My suggested timeline ...

By developer consensus I imagine you mean amongst yourself & Englebert? I don't know if there are any other active maintainers on the project (I don't know if you're looking for new maintainers?)

New suggested changes below: 

Move to declarative metadata using `setuptools`. I had wanted to avoid this as they use `setup.cfg` for metadata (support for PEP 621 metadata is planned but not implemented). 

This has no other implications, as all setuptools based behaviour remains.

Add deprecation notices where relevant

Introduce a new package `docutils-cli` that contains entrypoints etc -- acting as a thin wrapper over `docutils`. 

CLI based functionality could then move to the `docutils-cli` package per the rest of the timeline as you suggest. I'll update my patch accordingly, and will post it when done.



---

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

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Wed Jan 05, 2022 11:35 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.