Allow to upload downloads on already build versions

[ynikitenko]

Details

• Read the Docs project URL: https://readthedocs.org/projects/lena/
• Build URL (if applicable): https://readthedocs.org/projects/lena/builds/20069331/
• Read the Docs username (if applicable): https://readthedocs.org/profiles/ynikitenko/

Expected Result

I have several versions of my documentation. I think it would be good if they could be downloaded (not only the "stable" or "latest" version), because older versions are not any worse than the current one.
I tried to build for v0.5 explicitly (see the link to the build), but even though I have pdf and epub enabled in my RTD site settings, it didn't produce any pdf or epub for v0.5; it even has no html archive to download!
My "downloads" results are empty since v0.3. The build for v0.5 is declared to be "completed" (without errors).

Actual Result

Documentation for older versions should be available to download.
If one needs to tune Sphinx or other settings for that, it should not be allowed to set "pdf" and "epub" in RTD configuration (or it must signal an error).

[stsewd]

Hi, this is because you are using a config file https://github.com/ynikitenko/lena/blob/0.5/.readthedocs.yaml, options from the web UI are ignored when using a config file (there is a message about this in the settings menu).

So in order to re-build your docs with downloads enabled, you'll need to edit your config file, this may require you to create a new tag or force-push the current tag.

[ynikitenko]

You are right, thank you.

there is a message about this in the settings menu

this is also true. However, I have a feeling that information about that is lost in the documentation.
I copied my config file from this comment here, and had no idea that it has changed the whole results for my project.
Can that section in the Admin just be disabled if it detects a configuration file? Maybe it should be in red, not grey in the middle of the section?
Can the options from the Web interface be merged with the configuration file? I didn't set anything about output formats there at that time.

in order to re-build your docs with downloads enabled, you'll need to edit your config file, this may require you to create a new tag or force-push the current tag

Do you mean that my configuration file is taken from my previously tagged code? Could something be changed about that? I think if I could generate (or maybe upload?) new formats for old code versions, it would improve flexibility.

Which is also strange, is that I never prohibited (or "allowed") html download, but it is missing for the old versions as well.

UPD: I would add that it is not critical for me or my project, but this is what I think is good for documentation.

[stsewd]

Can that section in the Admin just be disabled if it detects a configuration file? Maybe it should be in red, not grey in the middle of the section?

We would need to check if all versions are using a config file, but I think it's easier to solve this by making the warning more prominent, I have opened an issue about this in our new theme (it's in a private repo).

Can the options from the Web interface be merged with the configuration file? I didn't set anything about output formats there at that time.

We don't support doing this on purpose, we want for the config file to be the source of truth of the build, so builds are reproducible.

Do you mean that my configuration file is taken from my previously tagged code? Could something be changed about that? I think if I could generate (or maybe upload?) new formats for old code versions, it would improve flexibility.

Yeah, the config file is taken from the current commit being built.

Which is also strange, is that I never prohibited (or "allowed") html download, but it is missing for the old versions as well.

When using a confg file, the default is to disable all downloadable content https://docs.readthedocs.io/en/stable/config-file/v2.html#formats.

[ynikitenko]

making the warning more prominent, I have opened an issue

this is really cool, thanks! Or maybe there could be a setting for me as a user to close that block at all? In case of forgetting that in a few years.

When using a config file, the default is to disable all downloadable content

It looks a bit strange, this difference in configuration. I would think that the defaults should not depend on the place they are set. Is there some special logic for creating such empty default [] for the config? I tried to find that, but could not. Hope I'm not taking much of your time!

[stsewd]

Is there some special logic for creating such empty default [] for the config? I tried to find that, but could not.

The reasoning behind that is that must users don't really care about having downloadable content, having it on by default meant that users would be building all formats, making their builds a little slow and consuming resources, and sometimes the build step of PDFs or other formats would break (this was when users realized they were building PDFs of their docs :D)

Recently, we changed the defaults of the UI to be unchecked as well (so projects without a config file also don't build all formats by default).

[ynikitenko]

Well, I still see some inconsistency. There is no way to disable downloadable documentation in the Admin panel (at least it is not on the page with other downloading settings).

Maybe many users don't need downloadable content, but I think that at least some people download this documentation, so it is better when it is present. Maybe it should be generated only for tagged releases, not for every update in that case? For me a downloadable pdf of my "latest" development version is not needed at all.

Program versions are important, because sometimes there are different requirements for them, and a user must stick to the version they have. So it would be good if they could have easily available documentation for that version as well.

Thank you for the solution proposed, but it looks not very good for me. I believe that one should not update version tags for the code. Packaging depends on these tags, and it is not very honest to users to update an already published tag.

I think that "produce pdf/epub" has no relation to reproducible builds. I would see it as a build option. In Sphinx we can say "generate pdf", so why can't we do that in ReadTheDocs? As a hack, we could at least upload these versions ourselves (but I'm not sure about security issues connected with this).

Another thing which I found not so nice is that after I created this configuration file (as an "official" bug fix), I even got no notification that my downloadable documentation is no longer created. I only noticed it after several years and two releases (this is probably my fault, but I mostly create documentation locally and only check that the RTD version is updated, without deeper tests).

So I would make this feature request. I understand that it is not straightforward in your existing model, but it looks more natural from my user's point of view. I would also add that I don't need downloadable documentation for every minor update, so it may save much resources and time. Thank you.

[stsewd]

So I would make this feature request. I understand that it is not straightforward in your existing model, but it looks more natural from my user's point of view

@ynikitenko what is the specific feature request you are asking for?

[ynikitenko]

@stsewd

• Allow to generate or upload downloadable documentation for published versions.
• Disable generation of downloadable documentation for each code update.

[humitos]

This feature request can now be achieved by using $READTHEDOCS_OUTPUT/<format> directory. Read more about this at https://docs.readthedocs.io/en/stable/build-customization.html#where-to-put-files