Ulibos commented 1 month ago

The issue

As many people (me included) tend to familiarize themselves with tools by extending examples, this particular flag is a big issue. It is the first ever flag one will see when they open up a Makefile or make.bat. Yet it's documentation is minimal and is hidden far away from a place a novice would reach out for in the first place. I literally had to search through github for the flag to find it mentioned in docs and find it's docs page by an excerpt from a nearby paragraph (because using the flag name directly in search engines does not help).

Why it's a problem

The fact that -M requires a very strict order of arguments and modifies provided paths is not apparent, yet it conflicts with the rest or the cli tool signature. It causes one to get unexpected export paths and there is no mention of it in the --help output which makes one to spend a lot of time debugging the issue.

Fix suggestion

--help output should display both call signatures and have at least a paragraph explaining what -M is intended for and how it affects args ordering:

usage: sphinx-build [OPTIONS] SOURCEDIR OUTPUTDIR [FILENAMES...]
       sphinx-build -M BUILDER SOURCEDIR OUTPUTDIR [OPTIONS]

Generate documentation from source files. sphinx-build generates documentation from the files
in SOURCEDIR and places it in OUTPUTDIR. It looks for 'conf.py' in SOURCEDIR...

positional arguments:
  sourcedir         path to documentation source files
  outputdir         path to output directory
  filenames         a list of specific files to rebuild. Ignored if -a is specified
  -M                special flag used for "one-click" builds. Must always
                    come first. Manages build and cache paths. If more
                    flexibility is needed, use -b instead and keep in mind
                    different signatures.

optional arguments:
  -h, --help        show this help message and exit
  --version         show program's version number and exit

I would even go as far as suggesting also adding at least a note to a Getting Started page for people to know that that example is NOT the default signature and maybe even mention it in make files themselves.

AA-Turner commented 1 month ago

PR welcome!

sphinx-doc / sphinx

Add usage example with -M flag in sphinx-build help. #12671

The issue

Why it's a problem

Fix suggestion