[v3] docs/sphinx: change default `role` to "any"

[PATCH v3 2/2] docs/sphinx: change default role to "any"

John Snow posted 2 patches 4 years, 4 months ago

Diff against v1 v2 v4 v5
Download mbox

Maintainers: Peter Maydell <peter.maydell@linaro.org>, Paolo Bonzini <pbonzini@redhat.com>, Darren Kenny <darren.kenny@oracle.com>, Alexandre Iooss <erdnaxe@crans.org>, Eric Blake <eblake@redhat.com>, Alexander Bulekov <alxndr@bu.edu>, Stefan Hajnoczi <stefanha@redhat.com>, Thomas Huth <thuth@redhat.com>, "Alex Bennée" <alex.bennee@linaro.org>, Markus Armbruster <armbru@redhat.com>, Mahmoud Mandour <ma.mandourr@gmail.com>, Qiuhao Li <Qiuhao.Li@outlook.com>, Bandan Das <bsd@redhat.com>

There is a newer version of this series

Expand all Fold all

[PATCH v3 2/2] docs/sphinx: change default role to "any"

Posted by John Snow 4 years, 4 months ago

This interprets single-backtick syntax in all of our Sphinx docs as a
cross-reference to *something*, including Python symbols.

From here on out, new uses of `backticks` will cause a build failure if
the target cannot be referenced.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/conf.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index ff6e92c6e2e..4d9f56601fc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -85,6 +85,11 @@
 # The master toctree document.
 master_doc = 'index'
 
+# Interpret `single-backticks` to be a cross-reference to any kind of
+# referenceable object. Unresolvable or ambiguous references will emit a
+# warning at build time.
+default_role = 'any'
+
 # General information about the project.
 project = u'QEMU'
 copyright = u'2021, The QEMU Project Developers'
-- 
2.31.1

Re: [PATCH v3 2/2] docs/sphinx: change default role to "any"

Posted by Peter Maydell 4 years, 4 months ago

On Thu, 23 Sept 2021 at 20:14, John Snow <jsnow@redhat.com> wrote:
>
> This interprets single-backtick syntax in all of our Sphinx docs as a
> cross-reference to *something*, including Python symbols.
>
> From here on out, new uses of `backticks` will cause a build failure if
> the target cannot be referenced.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/conf.py | 5 +++++
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

Re: [PATCH v3 2/2] docs/sphinx: change default role to "any"

Posted by Eduardo Habkost 4 years, 4 months ago

On Thu, Sep 23, 2021 at 03:13:23PM -0400, John Snow wrote:
> This interprets single-backtick syntax in all of our Sphinx docs as a
> cross-reference to *something*, including Python symbols.
> 
> From here on out, new uses of `backticks` will cause a build failure if
> the target cannot be referenced.
> 
> Signed-off-by: John Snow <jsnow@redhat.com>

Patch 1/2 demonstrates why patch 2/2 is useful.

Reviewed-by: Eduardo Habkost <ehabkost@redhat.com>

> ---
>  docs/conf.py | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/docs/conf.py b/docs/conf.py
> index ff6e92c6e2e..4d9f56601fc 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -85,6 +85,11 @@
>  # The master toctree document.
>  master_doc = 'index'
>  
> +# Interpret `single-backticks` to be a cross-reference to any kind of
> +# referenceable object. Unresolvable or ambiguous references will emit a
> +# warning at build time.
> +default_role = 'any'
> +
>  # General information about the project.
>  project = u'QEMU'
>  copyright = u'2021, The QEMU Project Developers'
> -- 
> 2.31.1
> 

-- 
Eduardo

[PATCH v3 1/2] docs: remove non-reference uses of single backticks
[PATCH v3 2/2] docs/sphinx: change default role to "any"