Hi Jon,

This series contain some patches from my parser-yaml one that
aren't directly related to it. It basically addresses some issues
at the build system. It also adds a script that I wrote with the
purpose of checking backward problems when building against
older toolchains.

IMO, the best is to merge and apply it before the YAML series.

I'll be respining the YAML later, with some additional changes.

Regards,
Mauro

Mauro Carvalho Chehab (6):
  docs: conf.py: properly handle include and exclude patterns
  docs: Makefile: disable check rules on make cleandocs
  scripts: scripts/test_doc_build.py: add script to test doc build
  scripts/test_doc_build.py: make capture assynchronous
  scripts: test_doc_build.py: better control its output
  docs: sphinx: add a file with the requirements for lowest version

 Documentation/Makefile                    |   2 +
 Documentation/conf.py                     |  67 +++-
 Documentation/doc-guide/sphinx.rst        |  23 ++
 Documentation/sphinx/min_requirements.txt |  10 +
 scripts/test_doc_build.py                 | 382 ++++++++++++++++++++++
 5 files changed, 480 insertions(+), 4 deletions(-)
 create mode 100644 Documentation/sphinx/min_requirements.txt
 create mode 100755 scripts/test_doc_build.py

-- 
2.49.0

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Hi Jon,
>
> This series contain some patches from my parser-yaml one that
> aren't directly related to it. It basically addresses some issues
> at the build system. It also adds a script that I wrote with the
> purpose of checking backward problems when building against
> older toolchains.
>
> IMO, the best is to merge and apply it before the YAML series.

OK, I've applied it, but ... someday, I think the test_doc_build tool
should be properly documented and put somewhere under tools/testing.

jon

Em Sat, 21 Jun 2025 13:39:09 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Hi Jon,
> >
> > This series contain some patches from my parser-yaml one that
> > aren't directly related to it. It basically addresses some issues
> > at the build system. It also adds a script that I wrote with the
> > purpose of checking backward problems when building against
> > older toolchains.
> >
> > IMO, the best is to merge and apply it before the YAML series.  
> 
> OK, I've applied it, but ... someday, I think the test_doc_build tool
> should be properly documented and put somewhere under tools/testing.

I added a better documentation for the tool at the v2.

With regards to move to tools, I'm not certain about it as I can see
advantages and disadvantages. 

Creating a new directory to have just one tool on it seems overkill
to me. Also, it is easier to type "scripts/..." than 
"tools/testing/build/..." :-)

There is another aspect: while doing conf.py and Documentation/Makefile
cleanup, I noticed that there are still lots of hacks inside them,
that are there from the early days when we adopted Sphinx. Perhaps
it could make sense to move part of the logic there to this new
build tool, which could, for instance, replace the logic inside
scripts/sphinx-pre-install and get rid of some magic at the Makefile
like the one which handles SPHINXDIRS.

So, at least for now, I would prefer to keep it under scripts.

Thanks,
Mauro

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> Em Sat, 21 Jun 2025 13:39:09 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
>
>> OK, I've applied it, but ... someday, I think the test_doc_build tool
>> should be properly documented and put somewhere under tools/testing.
>
> I added a better documentation for the tool at the v2.
>
> With regards to move to tools, I'm not certain about it as I can see
> advantages and disadvantages. 
>
> Creating a new directory to have just one tool on it seems overkill
> to me. Also, it is easier to type "scripts/..." than 
> "tools/testing/build/..." :-)
>
> There is another aspect: while doing conf.py and Documentation/Makefile
> cleanup, I noticed that there are still lots of hacks inside them,
> that are there from the early days when we adopted Sphinx. Perhaps
> it could make sense to move part of the logic there to this new
> build tool, which could, for instance, replace the logic inside
> scripts/sphinx-pre-install and get rid of some magic at the Makefile
> like the one which handles SPHINXDIRS.
>
> So, at least for now, I would prefer to keep it under scripts.

I pretty strongly disagree ... scripts/ is a dumping ground, nobody
really knows what all that stuff there is, nobody is responsible for it.
Something under tools/ would be more evident as to its purpose and
maintainership.  We could maybe just do tools/docs/ and move things like
sphinx-pre-install there as well...

Anyway, I won't try to hold up this work based on that, but now you know
how I feel...:)

jon

Em Sun, 22 Jun 2025 12:44:08 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Em Sat, 21 Jun 2025 13:39:09 -0600
> > Jonathan Corbet <corbet@lwn.net> escreveu:
> >  
> >> OK, I've applied it, but ... someday, I think the test_doc_build tool
> >> should be properly documented and put somewhere under tools/testing.  
> >
> > I added a better documentation for the tool at the v2.
> >
> > With regards to move to tools, I'm not certain about it as I can see
> > advantages and disadvantages. 
> >
> > Creating a new directory to have just one tool on it seems overkill
> > to me. Also, it is easier to type "scripts/..." than 
> > "tools/testing/build/..." :-)
> >
> > There is another aspect: while doing conf.py and Documentation/Makefile
> > cleanup, I noticed that there are still lots of hacks inside them,
> > that are there from the early days when we adopted Sphinx. Perhaps
> > it could make sense to move part of the logic there to this new
> > build tool, which could, for instance, replace the logic inside
> > scripts/sphinx-pre-install and get rid of some magic at the Makefile
> > like the one which handles SPHINXDIRS.
> >
> > So, at least for now, I would prefer to keep it under scripts.  
> 
> I pretty strongly disagree ... scripts/ is a dumping ground, nobody
> really knows what all that stuff there is, nobody is responsible for it.
> Something under tools/ would be more evident as to its purpose and
> maintainership.  We could maybe just do tools/docs/ and move things like
> sphinx-pre-install there as well...
> 
> Anyway, I won't try to hold up this work based on that, but now you know
> how I feel...:)

A tools/docs with all doc-related tool there is certainly appealing.
Yet, I would move all such scripts on a separate patchset.

Thanks,
Mauro