Maintain versioned API docs at the website. - #273
Merged
Conversation
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 14:50 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
2 times, most recently
from
March 6, 2025 15:16
b51a3d5 to
4de912a
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 15:17 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 15:19
4de912a to
141443c
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 15:20 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 15:21
141443c to
02eab7d
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 15:21 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 15:23
02eab7d to
32697ac
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 15:24 — with
GitHub Actions
Failure
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 15:35 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 15:40
7fe3c05 to
17d95d5
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 15:41 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 15:54
17d95d5 to
5ddf561
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 15:55 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:06
5ddf561 to
5d91fdc
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:09 — with
GitHub Actions
Failure
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:12 — with
GitHub Actions
Inactive
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:13 — with
GitHub Actions
Inactive
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:17
f11cfd0 to
899d56e
Compare
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:18 — with
GitHub Actions
Inactive
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:19 — with
GitHub Actions
Inactive
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:27
1456fed to
3e18182
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:29 — with
GitHub Actions
Failure
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:29 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:35
3e18182 to
361a82f
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:35 — with
GitHub Actions
Failure
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:35 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:36
361a82f to
694bfad
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:37 — with
GitHub Actions
Failure
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:37 — with
GitHub Actions
Failure
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:41
694bfad to
faa4640
Compare
myronmarston
had a problem deploying
to
rubygems.org
March 6, 2025 16:42 — with
GitHub Actions
Failure
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:42 — with
GitHub Actions
Inactive
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:45
faa4640 to
d5f150e
Compare
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:46 — with
GitHub Actions
Inactive
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:46 — with
GitHub Actions
Inactive
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 16:56
d5f150e to
743aa23
Compare
myronmarston
temporarily deployed
to
rubygems.org
March 6, 2025 16:57 — with
GitHub Actions
Inactive
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 17:13
743aa23 to
303a907
Compare
myronmarston
marked this pull request as ready for review
March 6, 2025 18:48
The approach I've taken is to commit an archive of each version's generated docs under `config/site/archived_docs`. This allows us to include all past versions of the docs in the built site without having to checkout past git commits or anything like that. And past versions of the docs work the same locally as they will when deployed. While I don't love storing generated artifacts in source control, the archive files are relatively modest in size (under 400KB) and I can't think of a better way to make this work. To get this working, I've used Goose to: - Define a new `site:archive_docs[vX.Y.Z]` task which depends on `site:build_docs` and then archives the produced docs into a new `.tar.gz` file. - Define a new `site:unpack_doc_archives` task which unpacks each doc archive into the appropriate directory. This has been added as a prerequisite task of `site:build_docs` so that it's done every time the docs get built. - Add the doc archives from the open source versions we've released (v0.19.0.0, v0.19.1.0, and v0.19.1.1). - Update the site navbar so that `Docs` is a dropdown that provides access to each available doc version. - Update the release workflow so that it archives the docs as part of cutting a release. (Unless it's a pre-release; then we skip). - Update gemspec metadata for each gem to link to the versioned docs instead of the `main` docs. Closes #2.
myronmarston
force-pushed
the
myron/multiple-doc-versions
branch
from
March 6, 2025 18:55
303a907 to
d174a36
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The approach I've taken is to commit an archive of each version's generated docs under
config/site/archived_docs. This allows us to include all past versions of the docs in the built site without having to checkout past git commits or anything like that. And past versions of the docs work the same locally as they will when deployed.While I don't love storing generated artifacts in source control, the archive files are relatively modest in size (under 400KB) and I can't think of a better way to make this work.
To get this working, I've used Goose to:
site:archive_docs[vX.Y.Z]task which depends onsite:build_docsand then archives the produced docs into a new.tar.gzfile.site:unpack_doc_archivestask which unpacks each doc archive into the appropriate directory. This has been added as a prerequisite task ofsite:build_docsso that it's done every time the docs get built.Docsis a dropdown that provides access to each available doc version.maindocs.Closes #2.
Testing
See #283 for an example PR produced by a dry-run of the release workflow. It has an archive for the new version.
Here's a screenshot of the new navbar in action: