[Python-Dev] cpython (3.3): Update Sphinx toolchain. (original) (raw)
anatoly techtonik techtonik at gmail.com
Mon Jan 13 20:56:20 CET 2014
- Previous message: [Python-Dev] cpython (3.3): Update Sphinx toolchain.
- Next message: [Python-Dev] cpython (3.3): Update Sphinx toolchain.
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
That's cool, but historical heritage makes the make argument somewhat confusing for new users. The immediate question I can sense is "What is the difference between build and make?"
To make (this word again) the critics constructive, let me pass some ideas about ideal user experience as I see it.
--[installation]-- 1 I install Sphinx. Two scenarios. 1.1 I am not a Python user - use installer 1.1.1 Installer should obviously install Python 1.1.2 And install sphinx command 1.1.3 And add sphinx to PATH 1.2 I am a Python user - use pip 1.2.1 pip should not alter my PATH (for virtualenv)
--[usage]-- 2 Two scenarios 2.1 sphinx as a system command from PATH 2.2 "python -m sphinx" for current virtualenv / test config
--[user experience]-- 3 These two invocations are equal
sphinx python -m sphinx
- They give the following ouput
Sphinx 1.2 Documentation Generator
Commands:
build build documentation init start new project [also quickstart] make helper for common build commands
Use "sphinx -h command" or "sphinx command --help" for details
I am not using sphinx ATM otherwise I'd spent more time to design ideal command set to get rid of build/make duality, but it should work ok.
Actually "sphinx" is a new command, so you may rethink the syntax for "build" arguments to contain "html" instead of dir names, and move dir names into parameters, because it is how it is most often used.
-- anatoly t.
On Sun, Jan 12, 2014 at 4:53 PM, Georg Brandl <g.brandl at gmx.net> wrote:
That's also planned, see https://bitbucket.org/birkenfeld/sphinx-new-make-mode/.
Georg Am 12.01.2014 09:49, schrieb anatoly techtonik: And cross-platform automation tools in Python instead of make https://bitbucket.org/birkenfeld/sphinx/issue/456/makepy-command-script -- anatoly t.
On Sun, Jan 12, 2014 at 11:12 AM, INADA Naoki <songofacandy at gmail.com> wrote: What about using venv and pip instead of svn?
Python-Dev mailing list Python-Dev at python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/techtonik%40gmail.com
- Previous message: [Python-Dev] cpython (3.3): Update Sphinx toolchain.
- Next message: [Python-Dev] cpython (3.3): Update Sphinx toolchain.
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]