| Message ID | 20210118094925.12654-1-yoann.congal@smile.fr |
|---|---|
| State | New |
| Headers | show |
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, + )
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] -=-=-=-=-=-=-=-=-=-=-=-
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 >> >> >> >> >>
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 > > > >
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