1. Patchew
  2. QEMU
  3. [Qemu-devel] [PATCH v2 0/2] docs/interop/bitmaps: rewrite and modernize doc
  4. View patch

[Qemu-devel] [PATCH v2 1/2] Makefile: add nit-picky mode to sphinx-build

John Snow posted 2 patches 6 years, 7 months ago
Maintainers: John Snow <jsnow@redhat.com>, Fam Zheng <fam@euphon.net>
There is a newer version of this series
[Qemu-devel] [PATCH v2 1/2] Makefile: add nit-picky mode to sphinx-build
Posted by John Snow 6 years, 7 months ago 
If we add references that don't resolve (or accidentally remove them),
it will be helpful to have an error message alerting us to that.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 Makefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 04a0d45050..ff9ce2ed4c 100644
--- a/Makefile
+++ b/Makefile
@@ -899,7 +899,7 @@ docs/version.texi: $(SRC_PATH)/VERSION
 sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html
 
 # Canned command to build a single manual
-build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
+build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
 # We assume all RST files in the manual's directory are used in it
 manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
 
-- 
2.20.1
Re: [Qemu-devel] [PATCH v2 1/2] Makefile: add nit-picky mode to sphinx-build
Posted by Vladimir Sementsov-Ogievskiy 6 years, 7 months ago 
23.04.2019 1:17, John Snow wrote:
> If we add references that don't resolve (or accidentally remove them),
> it will be helpful to have an error message alerting us to that.

accordingly to docs I've found, not error but warning.

> 
> Signed-off-by: John Snow <jsnow@redhat.com>

Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>

> ---
>   Makefile | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Makefile b/Makefile
> index 04a0d45050..ff9ce2ed4c 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -899,7 +899,7 @@ docs/version.texi: $(SRC_PATH)/VERSION
>   sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html
>   
>   # Canned command to build a single manual
> -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
> +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
>   # We assume all RST files in the manual's directory are used in it
>   manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
>   
> 


-- 
Best regards,
Vladimir
Re: [Qemu-devel] [PATCH v2 1/2] Makefile: add nit-picky mode to sphinx-build
Posted by John Snow 6 years, 7 months ago 

On 4/23/19 2:03 PM, Vladimir Sementsov-Ogievskiy wrote:
> 23.04.2019 1:17, John Snow wrote:
>> If we add references that don't resolve (or accidentally remove them),
>> it will be helpful to have an error message alerting us to that.
> 
> accordingly to docs I've found, not error but warning.
> 
Oh, true. I have to revise the document anyway, so I'll change my
phrasing here -- it won't cause the build to fail, but you will be able
to see the error when you build. I think it's helpful to have as a
mechanical check -- especially if we succeed in building generated ReST
documentation (eventually?...)

>>
>> Signed-off-by: John Snow <jsnow@redhat.com>
> 
> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> 
>> ---
>>   Makefile | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Makefile b/Makefile
>> index 04a0d45050..ff9ce2ed4c 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -899,7 +899,7 @@ docs/version.texi: $(SRC_PATH)/VERSION
>>   sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html
>>   
>>   # Canned command to build a single manual
>> -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
>> +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
>>   # We assume all RST files in the manual's directory are used in it
>>   manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
>>   
>>
> 
> 

-- 
—js
Re: [Qemu-devel] [PATCH v2 1/2] Makefile: add nit-picky mode to sphinx-build
Posted by Vladimir Sementsov-Ogievskiy 6 years, 7 months ago 
23.04.2019 21:06, John Snow wrote:
> 
> 
> On 4/23/19 2:03 PM, Vladimir Sementsov-Ogievskiy wrote:
>> 23.04.2019 1:17, John Snow wrote:
>>> If we add references that don't resolve (or accidentally remove them),
>>> it will be helpful to have an error message alerting us to that.
>>
>> accordingly to docs I've found, not error but warning.
>>
> Oh, true. I have to revise the document anyway, so I'll change my
> phrasing here -- it won't cause the build to fail, but you will be able
> to see the error when you build. I think it's helpful to have as a
> mechanical check -- especially if we succeed in building generated ReST
> documentation (eventually?...)

Hm, if we now don't have other warnings, we may also enable -W, to be strict.

> 
>>>
>>> Signed-off-by: John Snow <jsnow@redhat.com>
>>
>> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
>>
>>> ---
>>>    Makefile | 2 +-
>>>    1 file changed, 1 insertion(+), 1 deletion(-)
>>>
>>> diff --git a/Makefile b/Makefile
>>> index 04a0d45050..ff9ce2ed4c 100644
>>> --- a/Makefile
>>> +++ b/Makefile
>>> @@ -899,7 +899,7 @@ docs/version.texi: $(SRC_PATH)/VERSION
>>>    sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html
>>>    
>>>    # Canned command to build a single manual
>>> -build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
>>> +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -n -b html -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")
>>>    # We assume all RST files in the manual's directory are used in it
>>>    manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
>>>    
>>>
>>
>>
> 


-- 
Best regards,
Vladimir

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.