[PATCH] toaster-manual: Fix a warning related to the code-block directive

[PATCH] toaster-manual: Fix a warning related to the code-block directive

[Yoann Congal]

Fix the following warning by specifying the language (here : shell):
.../yocto/poky/documentation/toaster-manual/reference.rst:572: WARNING: Error in "code-block" directive:
1 argument(s) required, 0 supplied.

.. code-block::

   $ bitbake/lib/toaster/manage.py builddelete build_id

Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
---
 documentation/toaster-manual/reference.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/toaster-manual/reference.rst b/documentation/toaster-manual/reference.rst
index d2ab14c8e6..135968d40c 100644
--- a/documentation/toaster-manual/reference.rst
+++ b/documentation/toaster-manual/reference.rst
@@ -569,7 +569,7 @@ command would return something like the following::
 The ``builddelete`` command deletes data associated with a build. Access
 the command as follows:
 
-.. code-block::
+.. code-block:: shell
 
    $ bitbake/lib/toaster/manage.py builddelete build_id
 
-- 
2.20.1

Re: [docs] [PATCH] toaster-manual: Fix a warning related to the code-block directive

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 1412 bytes --]

On Wed, Jan 13, 2021 at 6:23 PM Yoann Congal <yoann.congal@smile.fr> wrote:

> Fix the following warning by specifying the language (here : shell):
> .../yocto/poky/documentation/toaster-manual/reference.rst:572: WARNING:
> Error in "code-block" directive:
> 1 argument(s) required, 0 supplied.
>

Which version of Sphinx are you using? I suspect an old version, in Sphinx
2+ (I think) it is no longer an error to omit the language. And I don't see
any warnings in my builds. In fact, we have 0 warning in the whole doc, and
we will try to avoid adding new ones!


>
> .. code-block::
>
>    $ bitbake/lib/toaster/manage.py builddelete build_id
>
> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
> ---
>  documentation/toaster-manual/reference.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/documentation/toaster-manual/reference.rst
> b/documentation/toaster-manual/reference.rst
> index d2ab14c8e6..135968d40c 100644
> --- a/documentation/toaster-manual/reference.rst
> +++ b/documentation/toaster-manual/reference.rst
> @@ -569,7 +569,7 @@ command would return something like the following::
>  The ``builddelete`` command deletes data associated with a build. Access
>  the command as follows:
>
> -.. code-block::
> +.. code-block:: shell
>
>     $ bitbake/lib/toaster/manage.py builddelete build_id
>
> --
> 2.20.1
>
>
> 
>
>

[-- Attachment #2: Type: text/html, Size: 2030 bytes --]

Re: [docs] [PATCH] toaster-manual: Fix a warning related to the code-block directive

[Yoann Congal]

[-- Attachment #1: Type: text/plain, Size: 1801 bytes --]

Hi !

Le mer. 13 janv. 2021 à 18:39, Nicolas Dechesne <nicolas.dechesne@linaro.org>
a écrit :

> On Wed, Jan 13, 2021 at 6:23 PM Yoann Congal <yoann.congal@smile.fr>
> wrote:
>
>> Fix the following warning by specifying the language (here : shell):
>> .../yocto/poky/documentation/toaster-manual/reference.rst:572: WARNING:
>> Error in "code-block" directive:
>> 1 argument(s) required, 0 supplied.
>>
>
> Which version of Sphinx are you using? I suspect an old version, in Sphinx
> 2+ (I think) it is no longer an error to omit the language. And I don't see
> any warnings in my builds. In fact, we have 0 warning in the whole doc, and
> we will try to avoid adding new ones!
>

Well you were right! I was running sphinx 1.8. I got no more warnings after
upgrading to sphinx 3.4.3.

Sorry about the noise !


>
>
>>
>> .. code-block::
>>
>>    $ bitbake/lib/toaster/manage.py builddelete build_id
>>
>> Signed-off-by: Yoann Congal <yoann.congal@smile.fr>
>> ---
>>  documentation/toaster-manual/reference.rst | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/documentation/toaster-manual/reference.rst
>> b/documentation/toaster-manual/reference.rst
>> index d2ab14c8e6..135968d40c 100644
>> --- a/documentation/toaster-manual/reference.rst
>> +++ b/documentation/toaster-manual/reference.rst
>> @@ -569,7 +569,7 @@ command would return something like the following::
>>  The ``builddelete`` command deletes data associated with a build. Access
>>  the command as follows:
>>
>> -.. code-block::
>> +.. code-block:: shell
>>
>>     $ bitbake/lib/toaster/manage.py builddelete build_id
>>
>> --
>> 2.20.1
>>
>>
>> 
>>
>>

-- 
Yoann Congal
Smile ECS - Expert technique
yoann.congal@smile.fr
+33 6 18 56 76 43

[-- Attachment #2: Type: text/html, Size: 3263 bytes --]

Re: [docs] [PATCH] toaster-manual: Fix a warning related to the code-block directive

[Quentin Schulz]

Hi Yoann, Nicolas,

On Thu, Jan 14, 2021 at 12:06:10PM +0100, Yoann Congal wrote:
> Hi !
> 
> Le mer. 13 janv. 2021 à 18:39, Nicolas Dechesne <nicolas.dechesne@linaro.org>
> a écrit :
> 
> > On Wed, Jan 13, 2021 at 6:23 PM Yoann Congal <yoann.congal@smile.fr>
> > wrote:
> >
> >> Fix the following warning by specifying the language (here : shell):
> >> .../yocto/poky/documentation/toaster-manual/reference.rst:572: WARNING:
> >> Error in "code-block" directive:
> >> 1 argument(s) required, 0 supplied.
> >>
> >
> > Which version of Sphinx are you using? I suspect an old version, in Sphinx
> > 2+ (I think) it is no longer an error to omit the language. And I don't see
> > any warnings in my builds. In fact, we have 0 warning in the whole doc, and
> > we will try to avoid adding new ones!
> >
> 
> Well you were right! I was running sphinx 1.8. I got no more warnings after
> upgrading to sphinx 3.4.3.
> 
> Sorry about the noise !
> 

And now I just discovered we don't have a requirements.txt or something
alike where we could ask for a min version of sphinx.

@Nicolas, any idea why we're not using requirements.txt so that one
could do pip install -r requirements.txt (and we could also enforce a
min version of Sphinx, the theme or pyyaml)? Or whatever mechanisms the
cool kids doing Python use nowadays?

Quentin

Re: [docs] [PATCH] toaster-manual: Fix a warning related to the code-block directive

[Nicolas Dechesne]

[-- Attachment #1: Type: text/plain, Size: 1643 bytes --]

On Thu, Jan 14, 2021 at 12:18 PM Quentin Schulz <
quentin.schulz@streamunlimited.com> wrote:

> Hi Yoann, Nicolas,
>
> On Thu, Jan 14, 2021 at 12:06:10PM +0100, Yoann Congal wrote:
> > Hi !
> >
> > Le mer. 13 janv. 2021 à 18:39, Nicolas Dechesne <
> nicolas.dechesne@linaro.org>
> > a écrit :
> >
> > > On Wed, Jan 13, 2021 at 6:23 PM Yoann Congal <yoann.congal@smile.fr>
> > > wrote:
> > >
> > >> Fix the following warning by specifying the language (here : shell):
> > >> .../yocto/poky/documentation/toaster-manual/reference.rst:572:
> WARNING:
> > >> Error in "code-block" directive:
> > >> 1 argument(s) required, 0 supplied.
> > >>
> > >
> > > Which version of Sphinx are you using? I suspect an old version, in
> Sphinx
> > > 2+ (I think) it is no longer an error to omit the language. And I
> don't see
> > > any warnings in my builds. In fact, we have 0 warning in the whole
> doc, and
> > > we will try to avoid adding new ones!
> > >
> >
> > Well you were right! I was running sphinx 1.8. I got no more warnings
> after
> > upgrading to sphinx 3.4.3.
> >
> > Sorry about the noise !
> >
>
> And now I just discovered we don't have a requirements.txt or something
> alike where we could ask for a min version of sphinx.
>
> @Nicolas, any idea why we're not using requirements.txt so that one
> could do pip install -r requirements.txt (and we could also enforce a
> min version of Sphinx, the theme or pyyaml)? Or whatever mechanisms the
> cool kids doing Python use nowadays?
>

We have a Pipfile, which is even cooler, no? but we don't specify any
version yet!

>
> Quentin
>

[-- Attachment #2: Type: text/html, Size: 2471 bytes --]

Re: [docs] [PATCH] toaster-manual: Fix a warning related to the code-block directive

[Quentin Schulz]

On Thu, Jan 14, 2021 at 12:22:58PM +0100, Nicolas Dechesne wrote:
> On Thu, Jan 14, 2021 at 12:18 PM Quentin Schulz <
> quentin.schulz@streamunlimited.com> wrote:
> 
> > Hi Yoann, Nicolas,
> >
> > On Thu, Jan 14, 2021 at 12:06:10PM +0100, Yoann Congal wrote:
> > > Hi !
> > >
> > > Le mer. 13 janv. 2021 à 18:39, Nicolas Dechesne <
> > nicolas.dechesne@linaro.org>
> > > a écrit :
> > >
> > > > On Wed, Jan 13, 2021 at 6:23 PM Yoann Congal <yoann.congal@smile.fr>
> > > > wrote:
> > > >
> > > >> Fix the following warning by specifying the language (here : shell):
> > > >> .../yocto/poky/documentation/toaster-manual/reference.rst:572:
> > WARNING:
> > > >> Error in "code-block" directive:
> > > >> 1 argument(s) required, 0 supplied.
> > > >>
> > > >
> > > > Which version of Sphinx are you using? I suspect an old version, in
> > Sphinx
> > > > 2+ (I think) it is no longer an error to omit the language. And I
> > don't see
> > > > any warnings in my builds. In fact, we have 0 warning in the whole
> > doc, and
> > > > we will try to avoid adding new ones!
> > > >
> > >
> > > Well you were right! I was running sphinx 1.8. I got no more warnings
> > after
> > > upgrading to sphinx 3.4.3.
> > >
> > > Sorry about the noise !
> > >
> >
> > And now I just discovered we don't have a requirements.txt or something
> > alike where we could ask for a min version of sphinx.
> >
> > @Nicolas, any idea why we're not using requirements.txt so that one
> > could do pip install -r requirements.txt (and we could also enforce a
> > min version of Sphinx, the theme or pyyaml)? Or whatever mechanisms the
> > cool kids doing Python use nowadays?
> >
> 
> We have a Pipfile, which is even cooler, no? but we don't specify any
> version yet!
> 

Didn't even know!

Kind of wary of this project though because of that part of their README:
" WARNING: This project is under active design and development. Nothing
is set in stone at this point in time."

But maybe something we could add to the docs
(https://docs.yoctoproject.org/ref-manual/system-requirements.html) as an
alternative installaion method?

Aaaaaand I should have read the README in yocto-docs more seriously :)

Thanks for the info,
Quentin

Re: [docs] [PATCH] toaster-manual: Fix a warning related to the code-block directive

[Yoann Congal]

[-- Attachment #1: Type: text/plain, Size: 2780 bytes --]

Hi !



Le jeu. 14 janv. 2021 à 12:46, Quentin Schulz <
quentin.schulz@streamunlimited.com> a écrit :

> On Thu, Jan 14, 2021 at 12:22:58PM +0100, Nicolas Dechesne wrote:
> > On Thu, Jan 14, 2021 at 12:18 PM Quentin Schulz <
> > quentin.schulz@streamunlimited.com> wrote:
> >
> > > Hi Yoann, Nicolas,
> > >
> > > On Thu, Jan 14, 2021 at 12:06:10PM +0100, Yoann Congal wrote:
> > > > Hi !
> > > >
> > > > Le mer. 13 janv. 2021 à 18:39, Nicolas Dechesne <
> > > nicolas.dechesne@linaro.org>
> > > > a écrit :
> > > >
> > > > > On Wed, Jan 13, 2021 at 6:23 PM Yoann Congal <
> yoann.congal@smile.fr>
> > > > > wrote:
> > > > >
> > > > >> Fix the following warning by specifying the language (here :
> shell):
> > > > >> .../yocto/poky/documentation/toaster-manual/reference.rst:572:
> > > WARNING:
> > > > >> Error in "code-block" directive:
> > > > >> 1 argument(s) required, 0 supplied.
> > > > >>
> > > > >
> > > > > Which version of Sphinx are you using? I suspect an old version, in
> > > Sphinx
> > > > > 2+ (I think) it is no longer an error to omit the language. And I
> > > don't see
> > > > > any warnings in my builds. In fact, we have 0 warning in the whole
> > > doc, and
> > > > > we will try to avoid adding new ones!
> > > > >
> > > >
> > > > Well you were right! I was running sphinx 1.8. I got no more warnings
> > > after
> > > > upgrading to sphinx 3.4.3.
> > > >
> > > > Sorry about the noise !
> > > >
> > >
> > > And now I just discovered we don't have a requirements.txt or something
> > > alike where we could ask for a min version of sphinx.
> > >
> > > @Nicolas, any idea why we're not using requirements.txt so that one
> > > could do pip install -r requirements.txt (and we could also enforce a
> > > min version of Sphinx, the theme or pyyaml)? Or whatever mechanisms the
> > > cool kids doing Python use nowadays?
> > >
> >
> > We have a Pipfile, which is even cooler, no? but we don't specify any
> > version yet!
> >
>
> Didn't even know!
>
> Kind of wary of this project though because of that part of their README:
> " WARNING: This project is under active design and development. Nothing
> is set in stone at this point in time."
>
> But maybe something we could add to the docs
> (https://docs.yoctoproject.org/ref-manual/system-requirements.html) as an
> alternative installaion method?
>
> Aaaaaand I should have read the README in yocto-docs more seriously :)
>

Me too!

Following this discussion, I made a proposal here :
https://lists.yoctoproject.org/g/docs/topic/patch_documentation_add_a/79919516
=> A simple Sphinx extension printing a warning on out-dated Sphinx version.
It will prevent this discussion from happening again in the future...

Yoann

[-- Attachment #2: Type: text/html, Size: 4204 bytes --]