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
sphinx
command. - Optionalization of
Makefile
/make.bat
generating on quickstart. - Stepwise deprecate and remove the existing
sphinx- *
commands - 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を高機能化する提案もいただいています(e3ae24f, #3741)。同時に、makeコマンドを捨ててPythonで書けるmake系コマンドに置き換える提案もあります (#3196)。こういった状況を終わらせ、シンプルな世界にするのがこの提案の目的です。
このため、大きく以下の変更を提案します。
sphinx
コマンドの導入による既存コマンドの引き継ぎMakefile
/make.bat
提供をオプション化- 段階的に既存の
sphinx-*
コマンドの廃止と削除 sphinx
コマンドの高機能化(サブコマンドプラグイン機能を提供等)
Step1: taking over existing command features by introducing sphinx
command.
- The
sphinx
command has global options such as--version
,--verbose
sphinx quickstart
invokesphinx-quickstart
feature.sphinx build html
invokesphinx-build -M html
feature- such
sphinx autodoc
invokesphinx-apidoc
and/orsphinx-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 invokesphinx
command instead ofsphinx-build
- Users can generate traditional
Makefile
/make.bat
by 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 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