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

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

On 2022-01-15, Adam Turner wrote:

> I don't think the `locale.setlocale` invoation is required any more in
> Python 3

It would be nice if we could drop this mantra. Could you find out whether this
is regarding to web-applications or command line applications?
The current [locale docs](https://docs.python.org/3/library/locale.html)
still say:

> Applications typically start with a call of

       import locale
       locale.setlocale(locale.LC_ALL, '')

> - The default writer has changed from `html5_polyglot` to `html4css1`
>   -- is this intentional? I note you re-overrode it in docutils-cli.py
>   to be `html5` again.

Actually, the default changed to "html" (which currently maps to "html4css1").
This is intended: "html is an alias for the default Docutils HTML writer."
https://docutils.sourceforge.io/docs/user/html.html#html

It would be strange, if the "canonical" entry point `python3 -m docutils`
would not use the official default HTML writer.
Users can easily set "html5" in a config file.  
(Changing the official default to "html5" is a different topic.)

When I first wrote `docutils-cli.py`, it did not support config files.
As I have a preference for the newer "html5" writer, I used it as default for
the new front-end.

> - Personally I'd only allow one way to set the components -- allowing
>   the fallbacks to be changed somewhat seems to go against TOOWTDI. Not
>   a big issue though.

I had to find a way to allow the above distiction: using the "official"
default for reader, parser, and writer in `python -m docutils` and be
backwards compatible with "docutils-cli.py" from an entry-point.

As a bonus, the fallback arguments `docutils.main()` offer extensions like
"myst" an easy way to define an entry point that allows users to select
components (which is not possible with the `publish_...()` functions as it
requires the 2-stage parsing introduced in docutils-cli.py.

Example: Instead of porting 5 (out of Docutil's 11) front ends to
`myst2...`, myst could provide one command line script `myst` based on the
entry point

~~~ myst/cli.py
  import docutils
  def main()
     docutils.main(parser='myst_parser.docutils_')
~~~

Caveat: for this to be useful, `docutils.main()` must also provide an
`config_section` argument.


---

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

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