[PATCH] manuals: add initial sphinx-lint support

[PATCH] manuals: add initial sphinx-lint support

[michael.opdenacker]

From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Makes it possible to catch errors not reported by sphinx,
such as idle spaces. After customization, this should be used
to enforce our syntax conventions, such as two spaces after a "-"
character to introduce a list item.

Just run "make sphinx-lint".

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
---
 documentation/Makefile |  3 +++
 documentation/README   | 14 ++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/documentation/Makefile b/documentation/Makefile
index f3b775b3ec..cacb51c036 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -53,6 +53,9 @@ stylecheck:
 	vale sync
 	vale $(VALEOPTS) $(VALEDOCS)
 
+sphinx-lint:
+	sphinx-lint
+
 epub: $(PNGs)
 	$(SOURCEDIR)/set_versions.py
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/documentation/README b/documentation/README
index 8035418cac..e1451789b6 100644
--- a/documentation/README
+++ b/documentation/README
@@ -165,6 +165,20 @@ To run Vale:
 
  $ make stylecheck
 
+Link checking the Yocto Project documentation
+=============================================
+
+To fix errors which are not reported by Sphinx itself,
+the project uses sphinx-lint (https://github.com/sphinx-contrib/sphinx-lint).
+
+To install sphinx-lint:
+
+ $ pip install sphinx-lint
+
+To run sphinx-lint:
+
+ $ make sphinxlint
+
 Sphinx theme and CSS customization
 ==================================
 
-- 
2.34.1

Re: [docs] [PATCH] manuals: add initial sphinx-lint support

[Jörg Sommer]

Michael Opdenacker via lists.yoctoproject.org schrieb am Sa 30. Mär, 17:36 (+0100):
> 
> Just run "make sphinx-lint".

> +sphinx-lint:
> +	sphinx-lint

> +To run sphinx-lint:
> +
> + $ make sphinxlint

Is a dash missing in this command?


Regards Jörg

-- 

Re: [docs] [PATCH] manuals: add initial sphinx-lint support

[Michael Opdenacker]

Hi Jörg

On 4/2/24 at 09:53, Jörg Sommer wrote:
> Michael Opdenacker via lists.yoctoproject.org schrieb am Sa 30. Mär, 17:36 (+0100):
>> Just run "make sphinx-lint".
>> +sphinx-lint:
>> +	sphinx-lint
>> +To run sphinx-lint:
>> +
>> + $ make sphinxlint
> Is a dash missing in this command?


Oops, good catch. It was a leftover from my first version.
Fixed.
Thanks!
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] manuals: add initial sphinx-lint support

[Quentin Schulz]

Hi Michael,

On 3/30/24 17:36, Michael Opdenacker via lists.yoctoproject.org wrote:
> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
> 
> Makes it possible to catch errors not reported by sphinx,
> such as idle spaces. After customization, this should be used
> to enforce our syntax conventions, such as two spaces after a "-"
> character to introduce a list item.
> 
> Just run "make sphinx-lint".
> 
> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
> ---
>   documentation/Makefile |  3 +++
>   documentation/README   | 14 ++++++++++++++
>   2 files changed, 17 insertions(+)
> 
> diff --git a/documentation/Makefile b/documentation/Makefile
> index f3b775b3ec..cacb51c036 100644
> --- a/documentation/Makefile
> +++ b/documentation/Makefile
> @@ -53,6 +53,9 @@ stylecheck:
>   	vale sync
>   	vale $(VALEOPTS) $(VALEDOCS)
>   
> +sphinx-lint:
> +	sphinx-lint
> +

I would pass $(SOURCEDIR) as argument as well.

Cheers,
Quentin

Re: [docs] [PATCH] manuals: add initial sphinx-lint support

[Michael Opdenacker]

Hi Quentin

On 4/2/24 at 11:59, Quentin Schulz wrote:
> Hi Michael,
>
> On 3/30/24 17:36, Michael Opdenacker via lists.yoctoproject.org wrote:
>> From: Michael Opdenacker <michael.opdenacker@bootlin.com>
>>
>> Makes it possible to catch errors not reported by sphinx,
>> such as idle spaces. After customization, this should be used
>> to enforce our syntax conventions, such as two spaces after a "-"
>> character to introduce a list item.
>>
>> Just run "make sphinx-lint".
>>
>> Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
>> ---
>>   documentation/Makefile |  3 +++
>>   documentation/README   | 14 ++++++++++++++
>>   2 files changed, 17 insertions(+)
>>
>> diff --git a/documentation/Makefile b/documentation/Makefile
>> index f3b775b3ec..cacb51c036 100644
>> --- a/documentation/Makefile
>> +++ b/documentation/Makefile
>> @@ -53,6 +53,9 @@ stylecheck:
>>       vale sync
>>       vale $(VALEOPTS) $(VALEDOCS)
>>   +sphinx-lint:
>> +    sphinx-lint
>> +
>
> I would pass $(SOURCEDIR) as argument as well.

Good idea!
I modified my branch.
Thanks
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com