[RFC PATCH] readthedocs: don't build extra formats

[RFC PATCH] readthedocs: don't build extra formats

[Alex Bennée]

We don't build the PDFs ourselves for the hosted docs and it looks
like rtd can't manage building PDFs now they have gone over a certain
size. Disable the extra formats so we can at least have the online
stuff again.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 .readthedocs.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 0b262469ce6..639f628612c 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -21,5 +21,3 @@ python:
   install:
     - requirements: docs/requirements.txt
 
-# We want all the document formats
-formats: all
-- 
2.47.2

Re: [RFC PATCH] readthedocs: don't build extra formats

[Daniel P. Berrangé]

On Mon, Aug 04, 2025 at 05:29:59PM +0100, Alex Bennée wrote:
> We don't build the PDFs ourselves for the hosted docs and it looks
> like rtd can't manage building PDFs now they have gone over a certain
> size. Disable the extra formats so we can at least have the online
> stuff again.

Regardless of build problems, IMHO, we should not have been building
the PDFs as no effort is being made to validate that the content is
formatting well under the layout constraints of PDFs

> 
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  .readthedocs.yml | 2 --
>  1 file changed, 2 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC PATCH] readthedocs: don't build extra formats

[Alex Bennée]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Mon, Aug 04, 2025 at 05:29:59PM +0100, Alex Bennée wrote:
>> We don't build the PDFs ourselves for the hosted docs and it looks
>> like rtd can't manage building PDFs now they have gone over a certain
>> size. Disable the extra formats so we can at least have the online
>> stuff again.
>
> Regardless of build problems, IMHO, we should not have been building
> the PDFs as no effort is being made to validate that the content is
> formatting well under the layout constraints of PDFs

True.

I will say the one thing I have found PDFs good for is uploading the
docs into a LLM context like NotebookLM. Otherwise you end up having to
add individual links which a) is a pain and b) is a potential DDoS
source if the model keeps hitting the host which as I'm sure everyone is
aware is a problem for FLOSS archives at the moment.

I would hope longer term there are better solutions for archiving our
docs as context if we want to provide it to things like bug assistants
or auto-reviews. I noticed virtiofsd is now using GitLabs AI tools to
aid MR processing.

>
>> 
>> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>> ---
>>  .readthedocs.yml | 2 --
>>  1 file changed, 2 deletions(-)
>
> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
>
> With regards,
> Daniel

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [RFC PATCH] readthedocs: don't build extra formats

[Daniel P. Berrangé]

On Tue, Aug 05, 2025 at 10:04:42AM +0100, Alex Bennée wrote:
> Daniel P. Berrangé <berrange@redhat.com> writes:
> 
> > On Mon, Aug 04, 2025 at 05:29:59PM +0100, Alex Bennée wrote:
> >> We don't build the PDFs ourselves for the hosted docs and it looks
> >> like rtd can't manage building PDFs now they have gone over a certain
> >> size. Disable the extra formats so we can at least have the online
> >> stuff again.
> >
> > Regardless of build problems, IMHO, we should not have been building
> > the PDFs as no effort is being made to validate that the content is
> > formatting well under the layout constraints of PDFs
> 
> True.
> 
> I will say the one thing I have found PDFs good for is uploading the
> docs into a LLM context like NotebookLM. Otherwise you end up having to
> add individual links which a) is a pain and b) is a potential DDoS
> source if the model keeps hitting the host which as I'm sure everyone is
> aware is a problem for FLOSS archives at the moment.

Is there a "single page HTML" option that would service that need ?

In general PDFs are a pretty awful format for programatically
consuming text, because they have no logical content structure
like HTML docs, so I'd expect HTML is a better format to feed
into any tool either LLM or not.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [RFC PATCH] readthedocs: don't build extra formats

[Alex Bennée]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Tue, Aug 05, 2025 at 10:04:42AM +0100, Alex Bennée wrote:
>> Daniel P. Berrangé <berrange@redhat.com> writes:
>> 
>> > On Mon, Aug 04, 2025 at 05:29:59PM +0100, Alex Bennée wrote:
>> >> We don't build the PDFs ourselves for the hosted docs and it looks
>> >> like rtd can't manage building PDFs now they have gone over a certain
>> >> size. Disable the extra formats so we can at least have the online
>> >> stuff again.
>> >
>> > Regardless of build problems, IMHO, we should not have been building
>> > the PDFs as no effort is being made to validate that the content is
>> > formatting well under the layout constraints of PDFs
>> 
>> True.
>> 
>> I will say the one thing I have found PDFs good for is uploading the
>> docs into a LLM context like NotebookLM. Otherwise you end up having to
>> add individual links which a) is a pain and b) is a potential DDoS
>> source if the model keeps hitting the host which as I'm sure everyone is
>> aware is a problem for FLOSS archives at the moment.
>
> Is there a "single page HTML" option that would service that need ?

There is an htmlzip format but I think that is just a bundle of html
files in a zip container. I'll see if there is an all one page option in
the docs.

>
> In general PDFs are a pretty awful format for programatically
> consuming text, because they have no logical content structure
> like HTML docs, so I'd expect HTML is a better format to feed
> into any tool either LLM or not.
>
> With regards,
> Daniel

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

Re: [RFC PATCH] readthedocs: don't build extra formats

[Stefan Hajnoczi]

On Mon, Aug 4, 2025 at 2:29 PM Alex Bennée <alex.bennee@linaro.org> wrote:
>
> We don't build the PDFs ourselves for the hosted docs and it looks
> like rtd can't manage building PDFs now they have gone over a certain
> size. Disable the extra formats so we can at least have the online
> stuff again.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  .readthedocs.yml | 2 --
>  1 file changed, 2 deletions(-)

Applied for QEMU v10.1.0-rc3. Thanks!

Stefan

>
> diff --git a/.readthedocs.yml b/.readthedocs.yml
> index 0b262469ce6..639f628612c 100644
> --- a/.readthedocs.yml
> +++ b/.readthedocs.yml
> @@ -21,5 +21,3 @@ python:
>    install:
>      - requirements: docs/requirements.txt
>
> -# We want all the document formats
> -formats: all
> --
> 2.47.2
>
>