Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add pass-through of sphinx-build CLI arguments to make.bat.new_t #6323

Closed
bskinn opened this issue Apr 25, 2019 · 5 comments
Closed

Add pass-through of sphinx-build CLI arguments to make.bat.new_t #6323

bskinn opened this issue Apr 25, 2019 · 5 comments
Labels
api:cmdline type:enhancement enhance or introduce a new feature

Comments

@bskinn
Copy link
Contributor

bskinn commented Apr 25, 2019

Is your feature request related to a problem? Please describe.

It's frustrating not being able to pass extra arguments to make.bat that then get provided to sphinx-build. E.g., > make html -Ean is not feasible. (This is a subset of #3741.)

Describe the solution you'd like

I'd like this capability to be added to Sphinx. I already have an implementation in my fork.

Describe alternatives you've considered

#3841 attempted a more-ambitious implementation, but was rejected due to likely too-great maintenance requirements. It looks like the whole makefile/make.bat setup will be obsoleted by #5618; but this seems like a simple enhancement to implement in the meantime.

Additional context

Screencap of implemented feature in action:

image

@bskinn bskinn added the type:enhancement enhance or introduce a new feature label Apr 25, 2019
@tk0miya
Copy link
Member

tk0miya commented Apr 28, 2019

make.bat already provides an environment variable %SPHINXOPTS% to give extra option on execution. I think this would help your case. Please try it :-)
https://www.sphinx-doc.org/en/master/man/sphinx-build.html#environment-variables

@bskinn
Copy link
Contributor Author

bskinn commented Apr 28, 2019

Yes, I know of %SPHINXOPTS already. Using an env variable for this purpose is awkward and slow, because I rarely want to use the same sphinx-build options in consecutive invocations, and as far as I know there's no elegant/quick way to tweak the environment for a particular shell command.

On Linux, make html O={options} works nicely, but I have not been able to get anything like that to work on Windows. If it does work somehow, and I've just been doing it wrong, then introducing the same %O% (or similar) shorthand variable as in Makefile would be most convenient. Then at least something terse like > set O=-E -a & make html should work ok.

@tk0miya
Copy link
Member

tk0miya commented May 6, 2019

Thank you for explanation. I understand your goal. But, personally, I feel a bit strange for giving parameters for sphinx-build as arguments of make.bat. I know windows is not under UNIX culture. But...

Note: I'm okay to add %O% shorthand to make.bat. But it would not resolve your concern.

@bskinn
Copy link
Contributor Author

bskinn commented May 8, 2019

I feel a bit strange for giving parameters for sphinx-build as arguments of make.bat.

Ahh, I hadn't thought of it from that angle -- yeah, make doesn't pass arguments through, so it would be odd for make.bat to do so.

I can open a PR to add the %O% shorthand option to make.bat--that at least will reduce the amount of typing necessary to adjust the build arguments. Which branch should I take out the PR against... probably 2.0, since this shouldn't be a breaking change?

@tk0miya
Copy link
Member

tk0miya commented May 12, 2019

@bskinn I think %O% does not break compatibility. So 2.0 branch is better for this. Could you send a PR please?

bskinn added a commit to bskinn/sphinx that referenced this issue May 13, 2019
The make.bat.new_t template now passes %O% as well as
%SPHINXOPTS% to `sphinx-build`, in parity with Makefile.new_t.

The sphinx-build documentation page was updated to explicitly note
$(O) and %O% as shortcut variables.

Closes sphinx-doc#6323, per the comment thread discussion.
bskinn added a commit to bskinn/sphinx that referenced this issue May 13, 2019
The make.bat_t and make.bat.new_t templates now pass %O% as well as
%SPHINXOPTS% to `sphinx-build`, in parity with Makefile.new_t.

The sphinx-build documentation page was updated to explicitly note
$(O) and %O% as shortcut variables.

Closes sphinx-doc#6323, per the comment thread discussion.
@tk0miya tk0miya closed this as completed May 13, 2019
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 5, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
api:cmdline type:enhancement enhance or introduce a new feature
Projects
None yet
Development

No branches or pull requests

2 participants