Consider the following piece of reST::
.. automodule:: sphinx.ext.autosummary
:members:
.. autosummary::
sphinx.ext.autosummary.Autosummary
This inserts an autosummary after the module docstring, but before
the members of the module. Without the change in this commit, this
would fail because `import_by_name` would attempt to import::
sphinx.ext.autosummary.sphinx.ext.autosummary.Autosumary
because the prefix (from the parent) is `sphinx.ext.autosummary`,
and the name is `sphinx.ext.autosummary.Autosummary`, which is able
to be imported from `sphinx.ext.autosummary`, but is not the way
that anyone would want to refer to it.
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Currently there is no mechanism to identify totally undocumented modules
in the coverage builder, unlike with partially documented modules.
Resolve this by introducing a new ``coverage_modules`` config option.
This is a list of modules that should be documented somewhere
within the documentation tree.
Any modules that are specified in the configuration value but
are not documented anywhere will result in a warning.
Likewise, any modules that are not in the config option but
are documented somewhere will result in a warning.
Signed-off-by: Stephen Finucane <stephen@that.guru>
- 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
This commit adds detection of ambiguous ``std:label`` and ``std:term`` references (due to case-insensitivity)
during loading and resolution of Intersphinx targets,
and emits a warning if found.
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>
Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>
The key issue this commit seeks to address, is that existing tools / documentation often lead users to mistakenly use object types and not role names, a classic example being `function` not `func`
Previously, the warning message for using e.g. `` external:function`target` `` (with `py` as the default domain), would be:
```
WARNING: role for external cross-reference not found: function
```
This gives no information to the user on how to fix the issue, even though there is actually quite an easy fix
This commit adds logic to create more specific / helpful warning messages, e.g.
```
WARNING: role for external cross-reference not found in domains 'py', 'std': 'function' (perhaps you meant one of: 'py:func', 'py:obj')
```
This goes through the same original logic but, if the role is not found, it will look if the role name is actually an available object type on the domain(s), and then suggest its related roles.
This commit also reverts #12133, which provided a (silent) fallback to auto convert an object type to a role name.
This commit fixes the issue of `objects.inv` denoting object names, whilst the `external` role only allows for role names.
As an example, take the `objects.inv` for the sphinx documentation, which contains:
```
py:function
compile : usage/domains/python.html#compile
```
A user might understandably expect that they could reference this using `` :external:py:function:`compile` ``, but actually this would previously error with:
```
WARNING: role for external cross-reference not found: py:function
```
this is because, `function` is the object type, yet `external` expects the related role name `func`.
It should not be necessary for the user to know about this distinction,
so in this commit, we add logic, to first look if the name relates to a role name (as previous, to not be back-breaking) but, if not, then also look if the name relates to an object that has a known role and, if so, use that.
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
