[PATCH] sphinx-lint: various fixes

[PATCH] sphinx-lint: various fixes

[Trevor Woerner]

A 'make sphinx-lint' pass found the following issues:
	trailing-whitespace
	missing-space-after-literal
	role-with-double-backticks
	missing-space-before-role (role missing opening tag colon)

Signed-off-by: Trevor Woerner <twoerner@gmail.com>
---
 documentation/dev-manual/devtool.rst                 | 2 +-
 documentation/dev-manual/start.rst                   | 4 ++--
 documentation/migration-guides/migration-5.2.rst     | 2 +-
 documentation/migration-guides/release-notes-5.2.rst | 4 ++--
 documentation/ref-manual/variables.rst               | 4 ++--
 5 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/documentation/dev-manual/devtool.rst b/documentation/dev-manual/devtool.rst
index 2f17d5093048..c82dc9c3334a 100644
--- a/documentation/dev-manual/devtool.rst
+++ b/documentation/dev-manual/devtool.rst
@@ -552,7 +552,7 @@ the two modes:
 
       This instance of VSCode uses plugins that are useful for the development
       of the application. ``devtool ide-sdk`` generates the necessary
-      ``extensions.json``, ``settings.json``, ``tasks.json``and ``launch.json``
+      ``extensions.json``, ``settings.json``, ``tasks.json`` and ``launch.json``
       configuration files for all the involved plugins.
 
       When the source code folder present in the workspace folder is opened in
diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
index 0f015d434041..21d3dce58c14 100644
--- a/documentation/dev-manual/start.rst
+++ b/documentation/dev-manual/start.rst
@@ -860,7 +860,7 @@ Initializing the Build Environment
 Before you can use Yocto you need to setup the build environment.
 From within the ``poky`` directory, source the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment
 setup script to define Yocto Project's build environment on your build host::
-    
-    $ source oe-init-build-env 
+
+    $ source oe-init-build-env
 
 Note, that this step will have to be repeated every time you open a new shell.
diff --git a/documentation/migration-guides/migration-5.2.rst b/documentation/migration-guides/migration-5.2.rst
index 9e9f466ade1e..77a11fe27047 100644
--- a/documentation/migration-guides/migration-5.2.rst
+++ b/documentation/migration-guides/migration-5.2.rst
@@ -83,7 +83,7 @@ systemd changes
    files by starting them via
    `Also <https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html#Also=>`__,
    the other service files were automatically added to the :term:`FILES` variable of
-   the same package. Example: 
+   the same package. Example:
 
    a.service contains::
 
diff --git a/documentation/migration-guides/release-notes-5.2.rst b/documentation/migration-guides/release-notes-5.2.rst
index 03f454bfc080..f0223b5f7290 100644
--- a/documentation/migration-guides/release-notes-5.2.rst
+++ b/documentation/migration-guides/release-notes-5.2.rst
@@ -25,7 +25,7 @@ New Features / Enhancements in |yocto-ver|
       :ref:`Shared State <overview-manual/concepts:Shared State>` for the
       dependencies. See :doc:`/test-manual/reproducible-builds`.
 
-   -  ``systemd``: Add term:`WATCHDOG_RUNTIME_SEC`: for controlling the
+   -  ``systemd``: Add :term:`WATCHDOG_RUNTIME_SEC`: for controlling the
       ``RuntimeWatchdogSec`` option in ``/etc/systemd/system.conf``.
 
    -  :term:`FIT_UBOOT_ENV` to allow including a u-boot script as a text in a
@@ -671,7 +671,7 @@ New Features / Enhancements in |yocto-ver|
    -  New ``bbverbnote`` log utility which can be used to print on the console
       (equivalent to the ``bb.verbnote`` Python implementation).
 
-   -  :ref:``ref-classes-grub-efi``: Add :term:`GRUB_TITLE` variable to set
+   -  :ref:`ref-classes-grub-efi`: Add :term:`GRUB_TITLE` variable to set
       custom GRUB titles.
 
    -  ``gawk``: Enable high precision arithmetic support by default (``mpfr``
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index d17f81036b7d..6a7c265d6b60 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -6131,7 +6131,7 @@ system and gives an overview of their function and contents.
       By default, no API key is used, which results in larger delays between API
       requests and limits the number of queries to the public rate limits posted
       at the `NVD developer's page <https://nvd.nist.gov/developers/start-here>`__.
-      
+
       NVD API keys can be requested through the
       `Request an API Key <https://nvd.nist.gov/developers/request-an-api-key>`__
       page. You can set this variable to the NVD API key in your ``local.conf`` file.
@@ -10404,7 +10404,7 @@ system and gives an overview of their function and contents.
 
          UBOOT_FIT_TEE_IMAGE ?= "tee-raw.bin"
 
-      If a relative path is provided, the file is expected to be relative to 
+      If a relative path is provided, the file is expected to be relative to
       U-Boot's :term:`B` directory. An absolute path can be provided too,
       e.g.::
 
-- 
2.44.0.501.g19981daefd7c

Re: [docs] [PATCH] sphinx-lint: various fixes

[Quentin Schulz]

Hi Trevor,

On 5/6/25 8:03 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> A 'make sphinx-lint' pass found the following issues:
> 	trailing-whitespace
> 	missing-space-after-literal
> 	role-with-double-backticks
> 	missing-space-before-role (role missing opening tag colon)
> 

I'll let Antonin confirm but I assume it would be a good idea to have 
separate commits so we could easily backport them to earlier releases? 
Or maybe you/someone can run sphinx-lint on older releases and send 
patches for those too?

The changes look fine (and necessary) to me :)

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

[...]

> diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
> index 0f015d434041..21d3dce58c14 100644
> --- a/documentation/dev-manual/start.rst
> +++ b/documentation/dev-manual/start.rst
> @@ -860,7 +860,7 @@ Initializing the Build Environment
>   Before you can use Yocto you need to setup the build environment.
>   From within the ``poky`` directory, source the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment
>   setup script to define Yocto Project's build environment on your build host::
> -
> -    $ source oe-init-build-env
> +
> +    $ source oe-init-build-env
>   

You could also remove one whitespace before the $ to respect the 
"code-blocks are aligned by three whitespaces" rule we have (and which 
seems to not be part of our documentation/standards.md :) ).

Thanks!
Quentin

Re: [docs] [PATCH] sphinx-lint: various fixes

[Trevor Woerner]

On Mon 2025-05-12 @ 09:50:07 AM, Quentin Schulz wrote:
> Hi Trevor,
> 
> On 5/6/25 8:03 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> > A 'make sphinx-lint' pass found the following issues:
> > 	trailing-whitespace
> > 	missing-space-after-literal
> > 	role-with-double-backticks
> > 	missing-space-before-role (role missing opening tag colon)
> > 
> 
> I'll let Antonin confirm but I assume it would be a good idea to have
> separate commits so we could easily backport them to earlier releases? Or
> maybe you/someone can run sphinx-lint on older releases and send patches for
> those too?

okay, waiting on Antonin

> 
> The changes look fine (and necessary) to me :)
> 
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> 
> [...]
> 
> > diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
> > index 0f015d434041..21d3dce58c14 100644
> > --- a/documentation/dev-manual/start.rst
> > +++ b/documentation/dev-manual/start.rst
> > @@ -860,7 +860,7 @@ Initializing the Build Environment
> >   Before you can use Yocto you need to setup the build environment.
> >   From within the ``poky`` directory, source the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment
> >   setup script to define Yocto Project's build environment on your build host::
> > -
> > -    $ source oe-init-build-env
> > +
> > +    $ source oe-init-build-env
> 
> You could also remove one whitespace before the $ to respect the
> "code-blocks are aligned by three whitespaces" rule we have (and which seems
> to not be part of our documentation/standards.md :) ).

ok

> Thanks!
> Quentin

Re: [docs] [PATCH] sphinx-lint: various fixes

[Antonin Godard]

On Mon May 12, 2025 at 11:03 PM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> On Mon 2025-05-12 @ 09:50:07 AM, Quentin Schulz wrote:
>> Hi Trevor,
>> 
>> On 5/6/25 8:03 PM, Trevor Woerner via lists.yoctoproject.org wrote:
>> > A 'make sphinx-lint' pass found the following issues:
>> > 	trailing-whitespace
>> > 	missing-space-after-literal
>> > 	role-with-double-backticks
>> > 	missing-space-before-role (role missing opening tag colon)
>> > 
>> 
>> I'll let Antonin confirm but I assume it would be a good idea to have
>> separate commits so we could easily backport them to earlier releases? Or
>> maybe you/someone can run sphinx-lint on older releases and send patches for
>> those too?
>
> okay, waiting on Antonin

Ultimately the best approach would be to run sphinx-lint on each branch, because
we might miss some lint warnings by simply backporting this patch.

Do you want to take care of it?

>> 
>> The changes look fine (and necessary) to me :)
>> 
>> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
>> 
>> [...]
>> 
>> > diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
>> > index 0f015d434041..21d3dce58c14 100644
>> > --- a/documentation/dev-manual/start.rst
>> > +++ b/documentation/dev-manual/start.rst
>> > @@ -860,7 +860,7 @@ Initializing the Build Environment
>> >   Before you can use Yocto you need to setup the build environment.
>> >   From within the ``poky`` directory, source the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment
>> >   setup script to define Yocto Project's build environment on your build host::
>> > -
>> > -    $ source oe-init-build-env
>> > +
>> > +    $ source oe-init-build-env
>> 
>> You could also remove one whitespace before the $ to respect the
>> "code-blocks are aligned by three whitespaces" rule we have (and which seems
>> to not be part of our documentation/standards.md :) ).
>
> ok

I can do it when applying your patch on master-next if that's ok to you, that's
an easy enough change. :)

Thanks!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] sphinx-lint: various fixes

[Trevor Woerner]

On Tue 2025-05-13 @ 10:17:05 AM, Antonin Godard wrote:
> On Mon May 12, 2025 at 11:03 PM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
> > On Mon 2025-05-12 @ 09:50:07 AM, Quentin Schulz wrote:
> >> Hi Trevor,
> >> 
> >> On 5/6/25 8:03 PM, Trevor Woerner via lists.yoctoproject.org wrote:
> >> > A 'make sphinx-lint' pass found the following issues:
> >> > 	trailing-whitespace
> >> > 	missing-space-after-literal
> >> > 	role-with-double-backticks
> >> > 	missing-space-before-role (role missing opening tag colon)
> >> > 
> >> 
> >> I'll let Antonin confirm but I assume it would be a good idea to have
> >> separate commits so we could easily backport them to earlier releases? Or
> >> maybe you/someone can run sphinx-lint on older releases and send patches for
> >> those too?
> >
> > okay, waiting on Antonin
> 
> Ultimately the best approach would be to run sphinx-lint on each branch, because
> we might miss some lint warnings by simply backporting this patch.
> 
> Do you want to take care of it?

Sure. In addition to master assume you want:
- kirkstone
- scarthgap
- walnascar
?

> >> 
> >> The changes look fine (and necessary) to me :)
> >> 
> >> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
> >> 
> >> [...]
> >> 
> >> > diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst
> >> > index 0f015d434041..21d3dce58c14 100644
> >> > --- a/documentation/dev-manual/start.rst
> >> > +++ b/documentation/dev-manual/start.rst
> >> > @@ -860,7 +860,7 @@ Initializing the Build Environment
> >> >   Before you can use Yocto you need to setup the build environment.
> >> >   From within the ``poky`` directory, source the :ref:`ref-manual/structure:\`\`oe-init-build-env\`\`` environment
> >> >   setup script to define Yocto Project's build environment on your build host::
> >> > -
> >> > -    $ source oe-init-build-env
> >> > +
> >> > +    $ source oe-init-build-env
> >> 
> >> You could also remove one whitespace before the $ to respect the
> >> "code-blocks are aligned by three whitespaces" rule we have (and which seems
> >> to not be part of our documentation/standards.md :) ).
> >
> > ok
> 
> I can do it when applying your patch on master-next if that's ok to you, that's
> an easy enough change. :)

Yes please.

Re: [docs] [PATCH] sphinx-lint: various fixes

[Antonin Godard]

Hi,

On Tue May 13, 2025 at 3:16 PM CEST, Trevor Woerner wrote:
> On Tue 2025-05-13 @ 10:17:05 AM, Antonin Godard wrote:
>> On Mon May 12, 2025 at 11:03 PM CEST, Trevor Woerner via lists.yoctoproject.org wrote:
>> > On Mon 2025-05-12 @ 09:50:07 AM, Quentin Schulz wrote:
>> >> Hi Trevor,
>> >> 
>> >> On 5/6/25 8:03 PM, Trevor Woerner via lists.yoctoproject.org wrote:
>> >> > A 'make sphinx-lint' pass found the following issues:
>> >> > 	trailing-whitespace
>> >> > 	missing-space-after-literal
>> >> > 	role-with-double-backticks
>> >> > 	missing-space-before-role (role missing opening tag colon)
>> >> > 
>> >> 
>> >> I'll let Antonin confirm but I assume it would be a good idea to have
>> >> separate commits so we could easily backport them to earlier releases? Or
>> >> maybe you/someone can run sphinx-lint on older releases and send patches for
>> >> those too?
>> >
>> > okay, waiting on Antonin
>> 
>> Ultimately the best approach would be to run sphinx-lint on each branch, because
>> we might miss some lint warnings by simply backporting this patch.
>> 
>> Do you want to take care of it?
>
> Sure. In addition to master assume you want:
> - kirkstone
> - scarthgap
> - walnascar

Yes, that's exactly those, thanks.

Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [PATCH] sphinx-lint: various fixes

[Antonin Godard]

On Tue, 06 May 2025 14:03:01 -0400, Trevor Woerner wrote:
> A 'make sphinx-lint' pass found the following issues:
> 	trailing-whitespace
> 	missing-space-after-literal
> 	role-with-double-backticks
> 	missing-space-before-role (role missing opening tag colon)
> 
> 
> [...]

Applied, thanks!

[1/1] sphinx-lint: various fixes
      commit: 6d4c67457e00a80dda4cd05bc5f05d8ebd8da5fc

Best regards,
-- 
Antonin Godard <antonin.godard@bootlin.com>