Provide sphinx command and integrate sphinx commands #5618
Description
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 (e3ae24f, #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.
- take over existing command features by introducing
sphinxcommand. - Optionalization of
Makefile/make.batgenerating on quickstart. - Stepwise deprecate and remove the existing
sphinx- *commands - Enhancement of
sphinxcommand (Provide subcommand plugin feature etc)
In Japanese
`Makefile` と `make.bat` は `sphinx-build` の薄いラッパーとしてmakeコマンドを使えるように提供されています。makeコマンドはmakeを使い慣れている人にとってはとても柔軟で分かりやすいものです。しかし、不慣れな人にとってはなにか問題が発生した場合に適切にレポートする妨げとなったり (#1693, #2521)、一部のシェル環境では動作しないといった不親切な面もありました(#3145)。こういった不親切な部分をより親切にしたい、より便利にしたいというMakefile/make.batを高機能化する提案もいただいています(e3ae24f, #3741)。同時に、makeコマンドを捨ててPythonで書けるmake系コマンドに置き換える提案もあります (#3196)。こういった状況を終わらせ、シンプルな世界にするのがこの提案の目的です。
このため、大きく以下の変更を提案します。
sphinxコマンドの導入による既存コマンドの引き継ぎMakefile/make.bat提供をオプション化- 段階的に既存の
sphinx-*コマンドの廃止と削除 sphinxコマンドの高機能化（サブコマンドプラグイン機能を提供等）
Step1: taking over existing command features by introducing sphinx command.
- The
sphinxcommand has global options such as--version,--verbose sphinx quickstartinvokesphinx-quickstartfeature.sphinx build htmlinvokesphinx-build -M htmlfeature- such
sphinx autodocinvokesphinx-apidocand/orsphinx-autogenfeature
Step2: Optionalization of Makefile / make.bat generating on quickstart.
Makefile/make.batwill not be created by default.- Users can generate new
Makefile/make.batby option that invokesphinxcommand instead ofsphinx-build - Users can generate traditional
Makefile/make.batby option that will be removed on Step3 because it invokesphinx-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 intlsub command. - multiple command target like:
make clean html
Timeline
Maybe..
- Sphinx-2.0.0: Step1 providing
sphinxcommand - Sphinx-3.0.0: Step2, Step3, Step4
- Sphinx-4.0.0: Step3, Step4