RetroSearch Browse

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://github.com/sphinx-doc/sphinx/issues/5618 below:

Provide `sphinx` command and integrate sphinx commands · Issue #5618 · sphinx-doc/sphinx · GitHub

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

TimKam, stsewd, mgeier, timhoffm, thejohnfreeman and 20 more

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4