Remove build-time field to avoid changing all pages on each build

[stsewd]

We are re-uploading all pages even if they didn't change anything because on each build we inject a different date-time.
As far as I can see, we aren't using this field anywhere in our code base.

[humitos]

The main reason of this PR is to not re-upload every single HTML file that hasn't changed at all on each build. The only reason why those files have changed is the build_date dumped into the READTHEDOCS_DATA object.

I'm 👍🏼 removing this. However, we are loosing some information with this change. People could be using the READTHEDOCS_DATA.build_date to do something we are not aware. I'm not super worried about this since this is an undocumented feature, tho, but just wanted to note this could "break" someones' docs.

Also, I wanted to mentioned that we talked about creating an endpoint, for example, /api/v3/metadata/?url=https://docs.readthedocs.io/en/stable/ that returns this READTHEDOCS_DATA object for this particular file/URL. That should be the canonical way to query this data and always be updated for that file.

[humitos]

As an example, for this page https://docs.readthedocs.io/en/stable/ the object looks like:

{
  "ad_free": false,
  "api_host": "https://readthedocs.org",
  "build_date": "2023-01-24T10:41:29Z",
  "builder": "sphinx",
  "canonical_url": null,
  "commit": "e1e7a186",
  "docroot": "/docs/user/",
  "features": {
    "docsearch_disabled": false
  },
  "global_analytics_code": "UA-17997319-1",
  "language": "en",
  "page": "index",
  "programming_language": "py",
  "project": "docs",
  "proxied_api_host": "/_",
  "source_suffix": ".rst",
  "subprojects": {},
  "theme": "sphinx_rtd_theme",
  "user_analytics_code": "UA-17997319-6",
  "version": "stable"
}

[humitos]

Wort to note that projects using https://github.com/mgeier/sphinx-last-updated-by-git will also have this "problem"

[humitos]

Hrm, we are adding the commit hash at the bottom of the page as well,

So, I think that even removing the build_date won't have too much effect. I mean, yes, re-building the same commit hash won't re-upload the HTML_, but re-building any other commit hash will re-upload all the pages anyways. So, I'm not sure if there are too much benefit from removing the build_date

[ericholscher]

The commit is also in the JSON. We could in theory return that from the footer API and add it to the page if we wanted to get really aggressive here. 🤷

[humitos]

I just noticed that we are including the commit in the HTML as well. So, I'm not sure removing the build_date is make any difference. That said, I'm 👍🏼 removing both of them or even more fields if they are required to not re-upload things.

Also, I want to note here that the new js client won't use this data. In fact, the new /readthedocs-config/ is returning the date when the build was built, which is exactly the same datetime we are hardcoding here. So, if required, it can be taken from there.

[davidfischer]

I added this feature (adding the build date to the output) that this PR removes. It was definitely more useful in the past where we had sync issues with remote storage or keeping multiple disks in sync. I'm OK with removing this feature and I think it will allow more efficient caching of files.

[ericholscher]

I'm 👍 on this change, but also agree we should remove the commit as well, to properly solve the problem.

If we need the commit, we should be able to get it from the server.

[stsewd]

Checked this locally, after removing the commit, pages aren't re-uploaded. But this will be noticed more when re-building the same commit, since our theme includes the commit.

https://github.com/readthedocs/sphinx_rtd_theme/blob/2442ab9ffdb8910f8484362cc8dfd165ca3ffb15/sphinx_rtd_theme/footer.html#L33-L38

[humitos]

Yeah, I mentioned that in a previous comment #119 (comment)

However, all the other projects not using our theme will benefit from this. Eventually, we can remove this feature from our theme and/or make it opt-in.