documentation: Add a simple Sphinx extension to check its version

Submitted by Yoann Congal on Jan. 18, 2021, 9:49 a.m. | Patch ID: 179192

Details

Message ID 20210118094925.12654-1-yoann.congal@smile.fr
State New
Headers show

Commit Message

Yoann Congal Jan. 18, 2021, 9:49 a.m.
Following this thread [1], point user to the README if they use an out-dated version of Sphinx.

[1]: [PATCH] toaster-manual: Fix a warning related to the code-block directive
     https://lists.yoctoproject.org/g/docs/topic/patch_toaster_manual_fix_a/79656195

Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
---
 documentation/conf.py                        |  3 ++-
 documentation/sphinx/sphinx-version-check.py | 25 ++++++++++++++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 documentation/sphinx/sphinx-version-check.py

Patch hide | download patch | download mbox

diff --git a/documentation/conf.py b/documentation/conf.py
index 407ea3292f..4376e67ee3 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -43,7 +43,8 @@  extensions = [
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.extlinks',
     'sphinx.ext.intersphinx',
-    'yocto-vars'
+    'yocto-vars',
+    'sphinx-version-check'
 ]
 autosectionlabel_prefix_document = True
 
diff --git a/documentation/sphinx/sphinx-version-check.py b/documentation/sphinx/sphinx-version-check.py
new file mode 100644
index 0000000000..174cdf0cb7
--- /dev/null
+++ b/documentation/sphinx/sphinx-version-check.py
@@ -0,0 +1,25 @@ 
+#!/usr/bin/env python
+
+"""
+Simple Sphinx extension checking if the current version will generate warnings
+"""
+
+import sphinx
+from sphinx.util import logging
+from sphinx.application import Sphinx
+
+__version__ = '1.0'
+
+def setup(app: Sphinx):
+    if sphinx.version_info < (3, 1, 0):
+        logger = logging.getLogger(__name__)
+        logger.warning(
+            "This version of sphinx is known to generate warnings not present "
+            "with an up-to-date version. See documentation/README for "
+            "installation instructions"
+        )
+
+    return dict(
+        version=__version__,
+        parallel_read_safe=True,
+    )

Comments

Nicolas Dechesne Jan. 18, 2021, 10:03 a.m.
hi Yoann,

On Mon, Jan 18, 2021 at 10:49 AM Yoann Congal <yoann.congal@smile.fr> wrote:

> Following this thread [1], point user to the README if they use an
> out-dated version of Sphinx.
>
> [1]: [PATCH] toaster-manual: Fix a warning related to the code-block
> directive
>
> https://lists.yoctoproject.org/g/docs/topic/patch_toaster_manual_fix_a/79656195
>
> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
>

I was about to reply that I like this patch a lot. and while i was looking
at it/testing, I found this in the sphinx docs:

needs_sphinx
If set to a major.minor version string like '1.1', Sphinx will compare it
with its version and refuse to build if it is too old. Default is no
requirement.

needs_extensions
This value can be a dictionary specifying version requirements for
extensions in extensions, e.g. needs_extensions =
{'sphinxcontrib.something': '1.5'}. The version strings should be in the
form major.minor. Requirements do not have to be specified for all
extensions, only for those you want to check.

they are existing configuration parameters we could use in conf.py. Do you
think you could check that and test? that seems to be exactly what we are
looking for!

---
>  documentation/conf.py                        |  3 ++-
>  documentation/sphinx/sphinx-version-check.py | 25 ++++++++++++++++++++
>  2 files changed, 27 insertions(+), 1 deletion(-)
>  create mode 100644 documentation/sphinx/sphinx-version-check.py
>
> diff --git a/documentation/conf.py b/documentation/conf.py
> index 407ea3292f..4376e67ee3 100644
> --- a/documentation/conf.py
> +++ b/documentation/conf.py
> @@ -43,7 +43,8 @@ extensions = [
>      'sphinx.ext.autosectionlabel',
>      'sphinx.ext.extlinks',
>      'sphinx.ext.intersphinx',
> -    'yocto-vars'
> +    'yocto-vars',
> +    'sphinx-version-check'
>  ]
>  autosectionlabel_prefix_document = True
>
> diff --git a/documentation/sphinx/sphinx-version-check.py
> b/documentation/sphinx/sphinx-version-check.py
> new file mode 100644
> index 0000000000..174cdf0cb7
> --- /dev/null
> +++ b/documentation/sphinx/sphinx-version-check.py
> @@ -0,0 +1,25 @@
> +#!/usr/bin/env python
> +
> +"""
> +Simple Sphinx extension checking if the current version will generate
> warnings
> +"""
> +
> +import sphinx
> +from sphinx.util import logging
> +from sphinx.application import Sphinx
> +
> +__version__ = '1.0'
> +
> +def setup(app: Sphinx):
> +    if sphinx.version_info < (3, 1, 0):
> +        logger = logging.getLogger(__name__)
> +        logger.warning(
> +            "This version of sphinx is known to generate warnings not
> present "
> +            "with an up-to-date version. See documentation/README for "
> +            "installation instructions"
> +        )
> +
> +    return dict(
> +        version=__version__,
> +        parallel_read_safe=True,
> +    )
> --
> 2.20.1
>
>
> 
>
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#843): https://lists.yoctoproject.org/g/docs/message/843
Mute This Topic: https://lists.yoctoproject.org/mt/79919516/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-
Yoann Congal Jan. 18, 2021, 11:22 a.m.
Le lun. 18 janv. 2021 à 11:03, Nicolas Dechesne <nicolas.dechesne@linaro.org>
a écrit :

> hi Yoann,
>
> On Mon, Jan 18, 2021 at 10:49 AM Yoann Congal <yoann.congal@smile.fr>
> wrote:
>
>> Following this thread [1], point user to the README if they use an
>> out-dated version of Sphinx.
>>
>> [1]: [PATCH] toaster-manual: Fix a warning related to the code-block
>> directive
>>
>> https://lists.yoctoproject.org/g/docs/topic/patch_toaster_manual_fix_a/79656195
>>
>> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
>>
>
> I was about to reply that I like this patch a lot. and while i was looking
> at it/testing, I found this in the sphinx docs:
>
> needs_sphinx
> If set to a major.minor version string like '1.1', Sphinx will compare it
> with its version and refuse to build if it is too old. Default is no
> requirement.
>
> needs_extensions
> This value can be a dictionary specifying version requirements for
> extensions in extensions, e.g. needs_extensions =
> {'sphinxcontrib.something': '1.5'}. The version strings should be in the
> form major.minor. Requirements do not have to be specified for all
> extensions, only for those you want to check.
>
> they are existing configuration parameters we could use in conf.py. Do you
> think you could check that and test? that seems to be exactly what we are
> looking for!
>

Hi Nicolas,

I didn't find these configurations... (And I was aiming to not break the
build even for old Sphinx)

needs_sphinx works really well :
 $ make html
Running Sphinx v3.0.0

Sphinx version error:
This project needs at least Sphinx v3.1 and therefore cannot be built with
this version.
make: *** [Makefile:35: html] Error 2

For needs_extensions, I don't know how to test with different extension
versions. But, AFAIK, we mostly use extensions packaged with Sphinx
distribution so needs_sphinx should be enough.

I'll send another patch.

---
>>  documentation/conf.py                        |  3 ++-
>>  documentation/sphinx/sphinx-version-check.py | 25 ++++++++++++++++++++
>>  2 files changed, 27 insertions(+), 1 deletion(-)
>>  create mode 100644 documentation/sphinx/sphinx-version-check.py
>>
>> diff --git a/documentation/conf.py b/documentation/conf.py
>> index 407ea3292f..4376e67ee3 100644
>> --- a/documentation/conf.py
>> +++ b/documentation/conf.py
>> @@ -43,7 +43,8 @@ extensions = [
>>      'sphinx.ext.autosectionlabel',
>>      'sphinx.ext.extlinks',
>>      'sphinx.ext.intersphinx',
>> -    'yocto-vars'
>> +    'yocto-vars',
>> +    'sphinx-version-check'
>>  ]
>>  autosectionlabel_prefix_document = True
>>
>> diff --git a/documentation/sphinx/sphinx-version-check.py
>> b/documentation/sphinx/sphinx-version-check.py
>> new file mode 100644
>> index 0000000000..174cdf0cb7
>> --- /dev/null
>> +++ b/documentation/sphinx/sphinx-version-check.py
>> @@ -0,0 +1,25 @@
>> +#!/usr/bin/env python
>> +
>> +"""
>> +Simple Sphinx extension checking if the current version will generate
>> warnings
>> +"""
>> +
>> +import sphinx
>> +from sphinx.util import logging
>> +from sphinx.application import Sphinx
>> +
>> +__version__ = '1.0'
>> +
>> +def setup(app: Sphinx):
>> +    if sphinx.version_info < (3, 1, 0):
>> +        logger = logging.getLogger(__name__)
>> +        logger.warning(
>> +            "This version of sphinx is known to generate warnings not
>> present "
>> +            "with an up-to-date version. See documentation/README for "
>> +            "installation instructions"
>> +        )
>> +
>> +    return dict(
>> +        version=__version__,
>> +        parallel_read_safe=True,
>> +    )
>> --
>> 2.20.1
>>
>>
>> 
>>
>>
Yoann Congal Jan. 18, 2021, 11:39 a.m.
Le lun. 18 janv. 2021 à 12:23, Yoann Congal via lists.yoctoproject.org
<yoann.congal=smile.fr@lists.yoctoproject.org> a écrit :

>
>
> Le lun. 18 janv. 2021 à 11:03, Nicolas Dechesne <
> nicolas.dechesne@linaro.org> a écrit :
>
>> hi Yoann,
>>
>> On Mon, Jan 18, 2021 at 10:49 AM Yoann Congal <yoann.congal@smile.fr>
>> wrote:
>>
>>> Following this thread [1], point user to the README if they use an
>>> out-dated version of Sphinx.
>>>
>>> [1]: [PATCH] toaster-manual: Fix a warning related to the code-block
>>> directive
>>>
>>> https://lists.yoctoproject.org/g/docs/topic/patch_toaster_manual_fix_a/79656195
>>>
>>> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
>>>
>>
>> I was about to reply that I like this patch a lot. and while i was
>> looking at it/testing, I found this in the sphinx docs:
>>
>> needs_sphinx
>> If set to a major.minor version string like '1.1', Sphinx will compare it
>> with its version and refuse to build if it is too old. Default is no
>> requirement.
>>
>> needs_extensions
>> This value can be a dictionary specifying version requirements for
>> extensions in extensions, e.g. needs_extensions =
>> {'sphinxcontrib.something': '1.5'}. The version strings should be in the
>> form major.minor. Requirements do not have to be specified for all
>> extensions, only for those you want to check.
>>
>> they are existing configuration parameters we could use in conf.py. Do
>> you think you could check that and test? that seems to be exactly what we
>> are looking for!
>>
>
> Hi Nicolas,
>
> I didn't find these configurations... (And I was aiming to not break the
> build even for old Sphinx)
>
> needs_sphinx works really well :
>  $ make html
> Running Sphinx v3.0.0
>
> Sphinx version error:
> This project needs at least Sphinx v3.1 and therefore cannot be built with
> this version.
> make: *** [Makefile:35: html] Error 2
>
> For needs_extensions, I don't know how to test with different extension
> versions. But, AFAIK, we mostly use extensions packaged with Sphinx
> distribution so needs_sphinx should be enough.
>
> I'll send another patch.
>

Done here : "[PATCH] documentation: Prevent building documentation with an
outdated version of sphinx" :
https://lists.yoctoproject.org/g/docs/topic/patch_documentation/79920786


>
> ---
>>>  documentation/conf.py                        |  3 ++-
>>>  documentation/sphinx/sphinx-version-check.py | 25 ++++++++++++++++++++
>>>  2 files changed, 27 insertions(+), 1 deletion(-)
>>>  create mode 100644 documentation/sphinx/sphinx-version-check.py
>>>
>>> diff --git a/documentation/conf.py b/documentation/conf.py
>>> index 407ea3292f..4376e67ee3 100644
>>> --- a/documentation/conf.py
>>> +++ b/documentation/conf.py
>>> @@ -43,7 +43,8 @@ extensions = [
>>>      'sphinx.ext.autosectionlabel',
>>>      'sphinx.ext.extlinks',
>>>      'sphinx.ext.intersphinx',
>>> -    'yocto-vars'
>>> +    'yocto-vars',
>>> +    'sphinx-version-check'
>>>  ]
>>>  autosectionlabel_prefix_document = True
>>>
>>> diff --git a/documentation/sphinx/sphinx-version-check.py
>>> b/documentation/sphinx/sphinx-version-check.py
>>> new file mode 100644
>>> index 0000000000..174cdf0cb7
>>> --- /dev/null
>>> +++ b/documentation/sphinx/sphinx-version-check.py
>>> @@ -0,0 +1,25 @@
>>> +#!/usr/bin/env python
>>> +
>>> +"""
>>> +Simple Sphinx extension checking if the current version will generate
>>> warnings
>>> +"""
>>> +
>>> +import sphinx
>>> +from sphinx.util import logging
>>> +from sphinx.application import Sphinx
>>> +
>>> +__version__ = '1.0'
>>> +
>>> +def setup(app: Sphinx):
>>> +    if sphinx.version_info < (3, 1, 0):
>>> +        logger = logging.getLogger(__name__)
>>> +        logger.warning(
>>> +            "This version of sphinx is known to generate warnings not
>>> present "
>>> +            "with an up-to-date version. See documentation/README for "
>>> +            "installation instructions"
>>> +        )
>>> +
>>> +    return dict(
>>> +        version=__version__,
>>> +        parallel_read_safe=True,
>>> +    )
>>> --
>>> 2.20.1
>>>
>>>
>>>
>>>
>>>
>
> --
> Yoann Congal
> Smile ECS - Expert technique
> yoann.congal@smile.fr
> +33 6 18 56 76 43
>
> 
>
>