- Remove now-removed configuration values
- Use obvious 'unset' defaults for ``project`` and ``author``
- Prefer 'e.g.' to 'ex.'
- Allow non-list sequence types in various configuration values
- Add types and defaults to every confval directive
A common "gotcha" of re-running `sphinx-autogen`, is that if there are changes it will not remove old files, leading to build errors for files not in a `toctree`
This commit introduces a `--remove-old` option to remove these files.
Note, a key detail here is that we don't want to simply clear the directory before running `sphinx-autogen`,
since this would lead to all files having a new `mtime`,
and then `sphinx-build` would rebuild all of them even if they have not changed.
So we must first collect the list of all correct files, then remove any not in the list.
A common "gotcha" of re-running `sphinx-apidoc`, is that if the modules API changes it will not remove old files, leading to build errors for files not in a `toctree`
This commit introduces a `--remove-old` option to remove these files.
Note, a key detail here is that we don't want to simply clear the directory before running `sphinx-apidoc`,
since this would lead to all files having a new `mtime`,
and then `sphinx-build` would rebuild all of them even if they have not changed.
So we must first collect the list of all correct files, then remove any not in the list.
The commit also improves some typing of the code and replace `os.path` by `pathlib.Path` in most instances
To describe the purpose more accurately, the `master_doc` is now renamed
to `root_doc`. The old name is still available. But it is recommeneded
to use new one from now on.
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#6323, per the comment thread discussion.
This is placed in a directory as this document will eventually be split
up. However, this is not the day to do this.
Signed-off-by: Stephen Finucane <stephen@that.guru>
The signature for the 'sphinx-apidoc' call differs between the man page
and the output of 'sphinx-apidoc --help'. Resolve this by considering
the 'sphinx-apidoc --help' output the canonical reference.
Signed-off-by: Stephen Finucane <stephen@that.guru>
Fixes: #4451
Add docs for '--module-first' option and 'SPHINX_APIDOC_OPTIONS'
environment variable. Per the closest thing we have to official man page
guidelines [1]:
ENVIRONMENT
lists all environment variables that affect the program or function
and how they affect it.
[1] https://linux.die.net/man/7/man-pages
Signed-off-by: Stephen Finucane <stephen@that.guru>
Fixes#2250
Indeed, if latex_engine is not appropriately set, the ``make latexpdf``
then fails because the Makefile in latex build repertory is the one for
pdflatex, not platex+dvipdfmx.
Besides, if language is 'ja', then latexpdf automatically uses the
platex latex_engine, hence the platex/dvipdfmx pipeline, and latexpdfja
is not needed.
For now, only removing documentation.
