Add sphinx._cli

[AA-Turner]

This is the first step towards a new sphinx command.

References: #5618, #6938

I took inspiration from @stephenfin's approach but this is a different tack.

Feature or Bugfix

• Feature

Sample output

(sphinx) I:\Development\sphinx>python -m sphinx._cli.__init__ --version
sphinx 5.3.0+/ac2a54de9

(sphinx) I:\Development\sphinx>python -m sphinx._cli.__init__ --help    
Usage: sphinx [--version] [--help] [--quiet] <command> [<args>]
                                                               
   Manage documentation with Sphinx.                           
                                                               
Options:                                                       
  --version, -V   Show the version and exit.                   
  --help, -h, -?  Show this message and exit.                  
  --quiet, -q     Only print errors and warnings.

For more information, visit <https://www.sphinx-doc.org/en/master/man/>.

(sphinx) I:\Development\sphinx>

A

[ashb]

(I came across this issue due to looking for a way to build multiple sphinx builders in a single command/call)

I'm not sure what Sphinx's policy is on pulling in dependencies, but might it be worth considering some of:

• https://click.palletsprojects.com/
• https://pypi.org/project/rich-click/
• https://pypi.org/project/typer/

They handle a lot of the "boilerplate" of dealing with arg parsing, subcommads, output and terminal color/encoding etc. (I'm absolutely not trying to bikeshed here)

[stephenfin]

Sample output

(sphinx) I:\Development\sphinx>python -m sphinx._cli.__init__ --version
sphinx 5.3.0+/ac2a54de9

(sphinx) I:\Development\sphinx>python -m sphinx._cli.__init__ --help    
Usage: sphinx [--version] [--help] [--quiet] <command> [<args>]
                                                               
   Manage documentation with Sphinx.                           
                                                               
Options:                                                       
  --version, -V   Show the version and exit.                   
  --help, -h, -?  Show this message and exit.                  
  --quiet, -q     Only print errors and warnings.

For more information, visit <https://www.sphinx-doc.org/en/master/man/>.

(sphinx) I:\Development\sphinx>

Out of curiosity, what's the rational for not providing a sphinx executable? I get that python -m <module-name> is the preferred pattern for something like pip because it helps you understand which version of Python you're running on (per python/cpython#66491), but for a tool like Sphinx the fact that it's written in Python should be irrelevant to anyone bar a Sphinx extension author or Sphinx core developer. Surely an unambiguous sphinx command would be preferable for "normal" people? 😄

[stephenfin]

Couple of comments inline

[AA-Turner]

Out of curiosity, what's the rational for not providing a sphinx executable?

This PR is intended to be the first in a series, and just introduces the new CLI infrastructure -- I don't want to provide sphinx before at least the main build command is ready.

A