Provide `sphinx` command and integrate sphinx commands

Proposal

I propose to integrate multiple commands into ONE sphinx command and provide existing commands as subcommands.

In Japanese

Subject: sphinx コマンドを提供し、sphinxの各コマンドを統合する

私は、複数あるコマンドを1つのsphinxコマンドに統合し、既存のコマンドをサブコマンドとして提供することを提案します。

Background

We have several sphinx related commands as:

• make (by Makefile, make.bat)
• sphinx-quickstart
• sphinx-build
• sphinx-apidoc
• sphinx-autogen

Makefile and make.bat are provided to use the make command as a thin wrapper for sphinx-build. The make command is very flexible and easy to understand for people familiar with make. However, it was unfortunate for some unfamiliar persons to hinder proper reporting when something goes wrong (#1693, #2521), or not to work in some shell environments (#3145). We are also receiving proposals to make Makefile/make.bat highly functional which wants to make such an unkind part more kind, more convenient (e3ae24f8, #3741). At the same time, there is also a proposal to discard the make command and replace it with a make command that can be written in Python (#3196).

It is the purpose of this proposal to finish these situations and make it a simple world.
For this reason, I propose the following changes to the following.

1. take over existing command features by introducing sphinx command.
2. Optionalization of Makefile / make.bat generating on quickstart.
3. Stepwise deprecate and remove the existing sphinx- * commands
4. Enhancement of sphinx command (Provide subcommand plugin feature etc)

In Japanese

`Makefile` と `make.bat` は `sphinx-build` の薄いラッパーとしてmakeコマンドを使えるように提供されています。makeコマンドはmakeを使い慣れている人にとってはとても柔軟で分かりやすいものです。しかし、不慣れな人にとってはなにか問題が発生した場合に適切にレポートする妨げとなったり (#1693, #2521)、一部のシェル環境では動作しないといった不親切な面もありました(#3145)。こういった不親切な部分をより親切にしたい、より便利にしたいというMakefile/make.batを高機能化する提案もいただいています(e3ae24f8, #3741)。同時に、makeコマンドを捨ててPythonで書けるmake系コマンドに置き換える提案もあります (#3196)。

こういった状況を終わらせ、シンプルな世界にするのがこの提案の目的です。
このため、大きく以下の変更を提案します。

1. sphinx コマンドの導入による既存コマンドの引き継ぎ
2. Makefile/make.bat 提供をオプション化
3. 段階的に既存の sphinx-* コマンドの廃止と削除
4. sphinx コマンドの高機能化（サブコマンドプラグイン機能を提供等）

Step1: taking over existing command features by introducing sphinx command.

• The sphinx command has global options such as --version, --verbose
• sphinx quickstart invoke sphinx-quickstart feature.
• sphinx build html invoke sphinx-build -M html feature
• such sphinx autodoc invoke sphinx-apidoc and/or sphinx-autogen feature

Step2: Optionalization of Makefile / make.bat generating on quickstart.

• Makefile / make.bat will not be created by default.
• Users can generate new Makefile/make.bat by option that invoke sphinx command instead of sphinx-build
• Users can generate traditional Makefile/make.bat by option that will be removed on Step3 because it invoke sphinx-build

Step3: Stepwise deprecate and remove the existing sphinx- * commands

• deprecating all sphinx- commands
• removing all sphinx- commands

Step4: enhancement of sphinx command

• command parameters from environment variables
• pluggable subcommands; ex. sphinx-intl will be able to provide sphinx intl sub command.
• multiple command target like: make clean html

Timeline

Maybe..

• Sphinx-2.0.0: Step1 providing sphinx command
• Sphinx-3.0.0: Step2, Step3, Step4
• Sphinx-4.0.0: Step3, Step4

Other related issues/PRs

• #6938
• #6939

Start by reviewing the existing entry points—Makefile, make.bat, sphinx-quickstart, sphinx-build, sphinx-apidoc, and sphinx-autogen—and the related issues #6938 and #6939. Done would require a decided, implemented plan for the unified sphinx command, subcommands, quickstart generation options, and the staged handling of existing sphinx-* commands.