Removes the need for various translators from raising a
`NotImplementedError` exception when missing support for a specific node
type. docutils will already raise [1][2] a `NotImplementedError`
exception for these cases. This help reduce the implementation inside
Sphinx as well as prevents the possible undesired replication of
unknown-node handling with third-party extensions [3].
In most cases, generating a warning message for an unsupported node type
can be preferred. Providing an indication that a node is not supported
can be easier for a user of Sphinx to understand a limitation of a
builder over a generic "not implemented" exception. This commit takes
the logging call which is already used by `texinfo` and applies it to
the `SphinxTranslator` base class -- which any Sphinx translator
implementation can use.
[1]: https://repo.or.cz/docutils.git/blob/d169015ee0f412cffd69b33654d8a119d99bc0f3:/docutils/nodes.py#l2048
[2]: https://repo.or.cz/docutils.git/blob/53716a13b48128af6045139d3cd2909f61e7ed8e:/docutils/nodes.py#l1897
[3]: https://github.com/sphinx-doc/sphinx/issues/9921
Signed-off-by: James Knight <james.d.knight@live.com>
When invoking the `coverage` on a Windows environment, the following
exception may generate:
...
raise CoverageException(f"Couldn't read {fname!r} as a config file")
coverage.exceptions.CoverageException: Couldn't read 'C:mycodesphinx/setup.cfg' as a config file
ERROR: InvocationError for command 'C:\mycode\sphinx\.tox\coverage\Scripts\python.EXE' -X dev -m pytest --durations 25 (exited with code 1)
Enclosing with configuration file with quotes can improve the handling
of a provided path on multiple platform types.
Signed-off-by: James Knight <james.d.knight@live.com>
If autodoc_unqualified_typehints feature enabled, autodoc suppresses the
leading module names of typehints of function signatures (ex.
`io.StringIO` -> `StringIO`)
To make the generated function signatures simple, this adds a new
parameter `unqualified_typehints` to sphinx.util.inspect:
stringify_signature() to suppress the leading module name of
typehints.
To make the generated function signatures simple, this adds a new
parameter `smartref` to sphinx.util.typing:stringify() to suppress the
leading module name from typehints.
`directivetype` is set to mimic `ClassDocumenter`. Reflect that.
`isinstance` would work on the enum members, but that is not what we want here.
`issubclass` raises a TypeError when called on objects that are not classes.
Now python domain supports the "~" prefix at the beginning of the
typehints of the function signatures:
.. py:function:: func(x: ~typing.Dict)
It's rescognized as the same as python reference roles do
(ex. :py:class:`~typing.Dict`).
