[Docutils-develop] [docutils:feature-requests] Re: #88 Unify Docutils CLI tools into `docutils-cli`

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

> Even with Sphinx, some features can only be customised from a
docutils.conf configuration file.

> The sttings_spec and document.settings are Docutils abstraction from
the different configuration ways (config-files/command line/programmatic).
Using document.settings should be possible without too much thinking
about the actual source of the setting value.

> An overview for programmatic use of the "settings" framework is given in
https://docutils.sourceforge.io/docs/api/runtime-settings.html#runtime-settings-processing-from-applications
(best read alongside pydoc3 -b output for the mentioned functions/classes).

Note I'm not proposing getting rid of the config, just loosening the direct relationship between the CLI-parsing part of Docutils and the settings/config part of Docutils. 

> We already have the docutils.core.publish_* "convenience functions" as
a high-level API for custom front-ends (both command-line and programmatic).

Hmm, perhaps we are talking at cross purposes. I'm talking about utility functions such as "take some RST and turn in into docutils nodes" (from halfway down https://github.com/sphinx-doc/sphinx/issues/8039, ignore the emotive language). 

What the user probably wanted is `docutils.core.publish_doctree(user_input_text).children`, but it is pretty hard to know this without knowing the internals of Docutils. A function named `get_nodes_from_rst` (or suchlike) would be a useful helper. 

There is currently a great degree of useage of random internal bits of Docutils, I think partially due to that these "medium level" helpers don't exist (sorry if I wasn't clear in what I meant here in the post above). 

> we want the components to be configurable from the command line or config file

I would challenge this, I would find this very surprising behaviour if a config file (in one of at least three places, or controlled by an environment file) populated defaults to the *components* being used. Given it also adds a lot of complexity, I'm not sure it is worth keeping?

>  implemented some of the abstractions and enhancements offered by Docutils in a different way.

The main challenge I had here was that subclasses can filter `settings_spec` (through `filter_settings_spec`). I've never seen this implemented in the way Docutils does it before -- if `settings_spec` tuples were treated as immutable, then it would be much easier to e.g. construct the parser object first and then use `parser.add_argument` as "intended". 

> simple front-ends in favour of one complex front end

I'll try another analogy (why not!) . When I'm using `ffmpeg`, it is "simple" to me as the end user to know that if I want to use different input or output encodings, I just pass the relevant flag. All I need to learn is the name of the base command, and that I pass the codec I want to `-c:a` and `-c:v`.  In this way it is "simpler" to remember and use as the number of commands goes up (and allows using aliases, which the per-format tools don't). 

The implementation might be somewhat more complex (although I would argue not much), but end-user simplicity is what counts.

If you're not conviced I'll drop the issue for now, I do think it would be good to at least unify the back-end implementations of the front-end tools.

> two packages at pypi

I don't think this is a good idea -- it increases confusion as there are two packages, but the "core" maintains all the complexity of needing to parse CLI stuff. Maybe later, if the core (or CLI) become more distinct.

> I propose to move it to docutils/writers/odtwriter/

+1

Will reply on 441 for the 441 things.

A





---

** [feature-requests:#88] Unify Docutils CLI tools into `docutils-cli`**

**Status:** open
**Group:** Default
**Created:** Sat Jan 15, 2022 10:11 PM UTC by Adam  Turner
**Last Updated:** Thu Jan 20, 2022 01:52 AM UTC
**Owner:** nobody


As noted at https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e/ef2d by @milde, 
> we should open a new ticket for the command line tool review

This is a tracker issue for this, and to allow discussion. 

I'll briefly re-outline my argument to (eventually) drop the `rst*` front-end tools, and only export `docutils-cli` (or `python -m docutils`). 

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

> 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 proposal isn't to remove them *\[the rst2 front-end tools\]* with no recourse, but to deprecate over a period of time, clearly marking identical drop-in commands at runtime to affected users. ... 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. 

(quotes taken from https://sourceforge.net/p/docutils/patches/186/#897a and https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e )

A


---

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

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