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

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

>Installation should be possible without dependencies other than stock Python and its standard library.

There's an intention in python packaging to become more standards based (PEPs 517, 518, 621, 660, etc) and less reliant on a single blessed tool (setuptools). 

There have been recent discussions of removing setuptools from the default python binaries (https://mail.python.org/archives/list/pyt...@py.../thread/3BVAUIQOEOXAULHVYQNLLQIZQQETX2EV/) -- the only constraint seems to be when `pip`  no longer needs it. 

My argument in short is that I don't believe installing Docutils from source using just the standard library will be possible for much longer -- `disutils` is being removed from the stdlib & will be removed in Python 3.12, and after that there are no bundled building mechanisms.

Flit (the system I proposed) has a strong focus / emphasis on boostraping -- see https://flit.readthedocs.io/en/latest/bootstrap.html. If you have the sources of flit and Docutils, you can end up with a functioning installation of Docutils using only the standard library -- would that be good enough reassurance?

> 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.

Will do

> I wonder if we could eat the cake and have it by moving the tools/ directory

I sort of did this in `_cli.py` -- see the section that starts `DEPRECATED ENTRY POINTS`. I switched from using the `publish_command_line` functions to routing through `docutils-cli` as it shows how they're all connected. 

If you wanted to keep the `.py` files in the tools directory then we could add aliases -- the contents of `rst2html5.py` would simply be:
```python
from docutils import _cli
_cli.publish_html5()
```

> templates for custom, home made front-ends

We could also add explicit templates in an `examples` folder or similar -- this would allow demonstrating potential usages of the API without needing to use it ourselves.

>A name change for the frontend tools is an API change that requires an advance warning in the RELEASE-NOTES

Of course, I can prepare a patch that only updates `RELEASE-NOTES`

> If implemented via an "entry point", the command name docutils-cli may also be simplified to docutils.

OK, will do. We can also keep the legacy `docutils-cli` as an alias and emit deprecation warnings until removal in the next major version.

> 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.

(note the below is entirely personal opinions, I am not David!)

I think a single front-end tool significantly simplifies a lot of things -- the `docutils-cli` wrapper is not complex, which gives it significant points in favour in my book. 

Most usage of Docutils today is programmatic, and not via the command line tools (see the table at the bottom of this post - it shows all the projects that have a full dependency on Docutils with over 500k downloads in the last month. Of those 8, none use the command line tools)

A converstation I wanted to have at a later date is starting to separate the application and library usages of Docutils (whilst keeping full backwards compatability). Having a single front-end command line interface would make that (theoretical) work significantly easier.

I also suspect (although the data does not exist) that most command line uses of the Docutils tools will be `rst2html(5)`.  This is already the default in `docutils-cli`, so it is a drop-in replacement.

My suggested timeline is: 
- 0.19.0: announce upcoming changes. Just the drop of support of `<3.7` may be big enough to release 0.19 -- if so could the future changes notice be included before you release it please?
- 0.20.0: add entrypoints, retain `rst2*` files in `tools/` (although no longer automatically copied into PATH), deprecate `rst2*` and `docutils-cli` commands at runtime (the deprecation message contains the replacement invocation needed)
- 0.21.0: Remove the deprecated `rst2*`  and `docutils-cli` aliases, leaving the single `docutils` command line tool.

I'd be interested in your thoughts on the proposed timeline -- is it workable? Is there anything I missed? (it is quite late here!)

A

------

package name     | downloads   | pin          | type
------------     | ---------   | ---          | ----
awscli           | 105,842,835 | >=0.10,<0.16 | pure docutils
apache-airflow   | 4,023,459   | <0.17        | with Sphinx
sphinx           | 3,843,715   | <0.18,>=0.14 | with Sphinx
readme-renderer  | 2,353,477   | >=0.13.1     | pure docutils
sphinx-rtd-theme | 1,740,846   | <0.18        | with Sphinx
c7n              | 945,488     | ==0.17.1     | with Sphinx
c7n-org          | 837,789     | ==0.17.1     | with Sphinx
recommonmark     | 611,332     | >=0.11       | with Sphinx

---

** [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 08:30 PM 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.