Add unified 'sphinx' command (WIP!) by stephenfin · Pull Request #6938 · sphinx-doc/sphinx

stephenfin · 2019-12-21T20:59:14Z

Feature or Bugfix

Feature

Purpose

Rather than having multiple separate executables - sphinx-build,
sphinx-quickstart, etc. - add a single sphinx command with multiple
subcommands.

Detail

TODO.

Relates

N/A

Let argparse do the heavy lifting here for us. Signed-off-by: Stephen Finucane <[email protected]>

stephenfin · 2019-12-21T22:04:30Z

@tk0miya I've only ported two of the four commands currently available in tree as part of this PR. Before I work on the remainder, I have a few questions I'd like your input on.

Does this idea make sense and are you happy with the approach?
I'm not planning to migrate makemode because I don't like it and don't think it's necessary as noted at Add 'Builder.epilog' attribute #4354 (comment). Do you agree?

Use argparse's built-in functionality to handle these as part of the parsing process itself, rather than as an afterthought. This changes behavior somewhat, as we'll now fail on the first missing file rather than list all missing files, but that doesn't seem like such a bad thing. Signed-off-by: Stephen Finucane <[email protected]>

Once again, this moves the logic into argparse and away from the meat of our application. Signed-off-by: Stephen Finucane <[email protected]>

This will form the basis of a future 'sphinx' executable and subcommands. Signed-off-by: Stephen Finucane <[email protected]>

This will make an upcoming diff far easier to read. Signed-off-by: Stephen Finucane <[email protected]>

This is the same as 'sphinx-quickstart' and represent the first step towards a unified executable. Note that this might look like a big diff, but most of it is just indentation due to the use of the class. Signed-off-by: Stephen Finucane <[email protected]>

As seen previously, this will make an upcoming diff far easier to read. Signed-off-by: Stephen Finucane <[email protected]>

This is the same as 'sphinx-build' and represent the second step towards a unified executable. Signed-off-by: Stephen Finucane <[email protected]>

stephenfin · 2019-12-22T00:03:53Z

As noted at #6939 (comment), another thing we could do here in change the behavior of the outputdir and maybe the sourcedir options for sphinx build. We could transition from:

sphinx-build sourcedir outputdir file_a file_b ...

to

sphinx build sourcedir file_a file_b ...

This would mean we'd need to be able to define outdir somewhere else. I'm suggesting conf.py (and later sphinx.ini, when I finally finish that work). We could provide a vanity option for people that really didn't want to do this, of course:

sphinx build -o outdir sourcedir file_a file_b

tk0miya · 2019-12-22T06:19:58Z

Does this idea make sense and are you happy with the approach?

Yes, of course! I just read a part of this patch yet. There might be trivial comments and requests later. But it looks good to me. I'll continue to read this later (maybe my new years task!).

I'm not planning to migrate makemode because I don't like it and don't think it's necessary as noted at #4354 (comment). Do you agree?

+1. new sphinx command should not follow historical interfaces. We can forget both make and non-make mode!

stephenfin · 2019-12-22T15:13:50Z

Good to hear. I am holding off on this until I determine whether I can configure the output directory as an optional flag (so sphinx build -o outdir srcdir instead of sphinx build srcdir outdir), as discussed at #6939 (comment). Other people have suggested this idea, such as #5618 (comment) though I disagree with -c conf.py being almost required. I'd prefer to default srcdir to the current directory.

tk0miya · 2019-12-22T15:13:07Z

sphinx/cmd/base.py

+
+        return parser
+
+    def run(self, argv: List[str]) -> int:


Please call initialization of locales at beginning of the application.

sphinx.locale.setlocale(locale.LC_ALL, '') sphinx.locale.init_console(os.path.join(package_dir, 'locale'), 'sphinx')

tk0miya · 2019-12-22T15:16:39Z

sphinx/cmd/build.py

-        except ValueError:
-            pass
-        confoverrides['html_context.%s' % key] = val
+    return BuildCommand._run(args)


We need to discuss sphinx build (new stye) is same as sphinx-build (old style). I still don't have an answer.

The only behavior change I've suggested so far is to go from:

sphinx-build sourcedir builddir [file, ...]

to

sphinx build sourcedir [file, ...] [-o builddir]

But perhaps there are other options that we think are badly named and should be renamed now? I hadn't thought of that so good idea 👍

It's just an idea, sphinx build html is so so good to me.

tk0miya · 2019-12-22T15:18:41Z

sphinx/cmd/quickstart.py

-                        help=__('quiet mode'))
-    parser.add_argument('--version', action='version', dest='show_version',
-                        version='%%(prog)s %s' % __display_version__)
+    'sphinx init' is an interactive tool that asks some questions about your


In some tools, init subcommand goes project initialization silently. So I wonder we should separate quickstart feature into sphinx init and sphinx quickstart (?) (or sphinx init --interactive).

Are you thinking of git init? I think it's okay for sphinx init to be interactive, so long as you can specify these options from the command line and avoid the interactive prompts. We do need some way to retrieve required information like project and author.

Yes, I was thinking of git init and bundle init. But I found npm init asks questions interactively. So please forget my comment.

We do need some way to retrieve required information like project and author.

Actually, project and author are not required configuration. So we can suppress all of questions.

Actually, project and author are not required configuration. So we can suppress all of questions.

Oh, I didn't know that. Good to know. However, is it really useful to ignore these? What advantage would sphinx init provide over touch conf.py if we didn't ask for these? I think it makes sense to ask for these at a minimum, even if people can skip past them.

It seems some users would like to do interactions more verbosely (see #6656). I still don't have an answer for it. But, as one of idea, it might be better to provide both silent and verbose way.

Note: silent means only "less". It does not equal to no question.

Sorry for the delay. How about we make interactive not the default by adding an --interactive flag? With this flag, we would request all configuration options in an interactive manner from the user, but users that don't want to do this can simply pass the relevant args they care about, e.g. --project? That would satisfy the request of #6656 while not annoying people like you that just wants to start a really quick project? The other alternative is a combination of --quick (default) and --full arguments, with the latter enabling configuration of extensions etc. What do you think?

I prefer an option like --full. It is too much to choose non interactive mode by default to me. But it is annoying to me to list all configurations. I think it is difficult to choose to appropriate options or extensions for standard users. So it would be better to ask minimum configurations by default.

AA-Turner · 2025-01-30T08:31:33Z

Closing this, we intend to have a unified sphinx command through the _cli sub-package, which is slowly progressing. Thanks to Stephen for originally proposing a design for this feature!

A

sphinx-build: Use 'argparse.FileType'

7711902

Let argparse do the heavy lifting here for us. Signed-off-by: Stephen Finucane <[email protected]>

stephenfin added 7 commits December 21, 2019 22:08

sphinx-build: Add Actions for '-D', '-A' options

d0696ae

Once again, this moves the logic into argparse and away from the meat of our application. Signed-off-by: Stephen Finucane <[email protected]>

cmd: Add base command

5806f5d

This will form the basis of a future 'sphinx' executable and subcommands. Signed-off-by: Stephen Finucane <[email protected]>

cmd: Split 'quickstart.main' into two

9715b1c

This will make an upcoming diff far easier to read. Signed-off-by: Stephen Finucane <[email protected]>

cmd: Rearrange 'build' file

5c52af2

As seen previously, this will make an upcoming diff far easier to read. Signed-off-by: Stephen Finucane <[email protected]>

cmd: Add 'sphinx build' command

5e33716

This is the same as 'sphinx-build' and represent the second step towards a unified executable. Signed-off-by: Stephen Finucane <[email protected]>

stephenfin force-pushed the sphinx-centralized-command branch from 25434be to 5e33716 Compare December 21, 2019 22:18

stephenfin mentioned this pull request Dec 21, 2019

[RFC] Simplified 'sphinx-build' #6939

Closed

shimizukawa mentioned this pull request Dec 22, 2019

Provide sphinx command and integrate sphinx commands #5618

Open

tk0miya reviewed Dec 22, 2019

View reviewed changes

tk0miya mentioned this pull request Apr 29, 2020

Add .pre-commit-hooks.yaml configurations #7558

Closed

tk0miya mentioned this pull request Apr 14, 2021

Replace Makefile/make.bat with a Python script? #3196

Closed

mgeier mentioned this pull request Jul 19, 2021

Support configuration files for sphinx-build to specify common options #9473

Closed

AA-Turner mentioned this pull request Sep 28, 2022

Add sphinx._cli #10877

Merged

AA-Turner added this to the some future version milestone Apr 29, 2023

AA-Turner mentioned this pull request Aug 29, 2023

Exposing more than just sphinx-build to python -m sphinx #11656

Closed

AA-Turner closed this Jan 30, 2025

stephenfin deleted the sphinx-centralized-command branch January 30, 2025 16:55

github-actions bot locked as resolved and limited conversation to collaborators Feb 28, 2025

Uh oh!

Conversation

stephenfin commented Dec 21, 2019

Feature or Bugfix

Purpose

Detail

Relates

Uh oh!

stephenfin commented Dec 21, 2019

Uh oh!

stephenfin commented Dec 22, 2019

Uh oh!

tk0miya commented Dec 22, 2019

Uh oh!

stephenfin commented Dec 22, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephenfin Dec 22, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AA-Turner commented Jan 30, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stephenfin Dec 22, 2019 •

edited

Loading