diff mbox series

docs: Print warning when running Sphinx 3.x and newer

Message ID 20201014223356.324990-1-ehabkost@redhat.com
State New
Headers show
Series docs: Print warning when running Sphinx 3.x and newer | expand

Commit Message

Eduardo Habkost Oct. 14, 2020, 10:33 p.m. UTC
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(+)

Comments

Peter Maydell Oct. 15, 2020, 12:38 p.m. UTC | #1
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
Eduardo Habkost Oct. 15, 2020, 4:03 p.m. UTC | #2
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'


-- 
Eduardo
diff mbox series

Patch

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.