| Message ID | 20201014223356.324990-1-ehabkost@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs: Print warning when running Sphinx 3.x and newer | expand |
On Wed, 14 Oct 2020 at 23:34, Eduardo Habkost <ehabkost@redhat.com> wrote: > > This won't prevent the docs from being built, but will let people > know Sphinx 3.x is not fully supported yet. > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> Sphinx 3.0.1 works fine for me, so I think we probably want to set the cutoff somewhere else than just 3.0. thanks -- PMM
On Thu, Oct 15, 2020 at 01:38:49PM +0100, Peter Maydell wrote: > On Wed, 14 Oct 2020 at 23:34, Eduardo Habkost <ehabkost@redhat.com> wrote: > > > > This won't prevent the docs from being built, but will let people > > know Sphinx 3.x is not fully supported yet. > > > > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> > > Sphinx 3.0.1 works fine for me, so I think we probably > want to set the cutoff somewhere else than just 3.0. Sphinx 3.0.0+ doesn't know how to handle macro documentation generated by kernel-doc: Running Sphinx v3.0.1 building [mo]: targets for 0 po files that are out of date building [html]: targets for 22 source files that are out of date updating environment: [new config] 22 added, 0 changed, 0 removed reading sources... [100%] testing Warning, treated as error: /home/ehabkost/rh/proj/virt/qemu/docs/../include/qom/object.h:155:Error in declarator If declarator-id with parameters (e.g., 'void f(int arg)'): Invalid C declaration: Expected identifier in nested name. [error at 25] DECLARE_INSTANCE_CHECKER ( InstanceType, OBJ_NAME, TYPENAME) -------------------------^ If parenthesis in noptr-declarator (e.g., 'void (*f(int arg))(double)'): Error in declarator or parameters Invalid C declaration: Expecting "(" in parameters. [error at 39] DECLARE_INSTANCE_CHECKER ( InstanceType, OBJ_NAME, TYPENAME) ---------------------------------------^ make: *** [Makefile.ninja:9897: docs/devel.stamp] Error 2 make: *** Deleting file 'docs/devel.stamp'
diff --git a/docs/conf.py b/docs/conf.py index 00e1b750e2..1d92e65d12 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,6 +40,11 @@ if sys.version_info < (3,6): raise ConfigError( "QEMU requires a Sphinx that uses Python 3.6 or better\n") +# Sphinx 3.x may be able to build the documents, but it may generate +# warnings and/or the document may be formatted incorrectly +if sphinx.version_info >= (3, 0): + sys.stderr.write('WARNING: Sphinx 3.x is not fully supported by QEMU\n') + # The per-manual conf.py will set qemu_docdir for a single-manual build; # otherwise set it here if this is an entire-manual-set build. # This is always the absolute path of the docs/ directory in the source tree.
This won't prevent the docs from being built, but will let people know Sphinx 3.x is not fully supported yet. Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> --- docs/conf.py | 5 +++++ 1 file changed, 5 insertions(+)