-
-
Notifications
You must be signed in to change notification settings - Fork 6.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
add versioned documentation to the website #5541
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice, thanks for doing this! Can you post some screenshots too?
With all the versioning I'm afraid we're sooner or later need to move website to its own repo, as it will grow fast
website/pages/en/versions.js
Outdated
<header className="postHeader"> | ||
<h2>{siteConfig.title + ' Versions'}</h2> | ||
</header> | ||
<a name="latest" /> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Anchors should have a href
attribute, you can use a button instead. Please fix this in other places too,
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That page was auto-generated by Docusaurus and I think it's intended. I think it should act as an in-page anchor so one can link to that part of the page directly, like this: https://facebook.github.io/relay/en/versions.html#latest.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ah, this is so wrong. The name
attr on anchors is obsolete. They should just use id
s. Mind filing an issue or PR fixing that? There's no need to create artificial pseudo anchor too.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I opened a PR for that as it's pretty straightforward (here). I also updated this PR by removing the redundant anchor tags and using id
s instead.
@@ -0,0 +1,328 @@ | |||
--- | |||
id: version-22.2.2-cli |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we use just major and minor versions for docs? I'd rather have docs for "Jest 22.2". Patches are for fixes
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Definitely 👍
The version is showing at the top right corner (and the versions page). I think it may be a bit confusing to use semver with only two numbers (e.g. 22.2
). What do you think about naming versions like this: 22.2.x
or possibly 22.2.0
?
Please let me know and I'll push a fix.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
22.2.X seems reasonable
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I can see on React Native's website (https://facebook.github.io/react-native/versions.html) that they use just major and minor versions (0.53
), skipping the patch version (like @thymikee suggested).
Looking at it again I think it looks better without the X
, what do you guys think?
@thymikee thanks for the review 🙂 Here's a screenshot of how the new versions page looks, it can be accessed by clicking on the version next to the Jest logo (top left corner). Other than that and the version at the top it looks exactly the same. I agree that separating the documentation to its own repo should probably happen sooner or later. We can also consider only having a small number of documented versions of Jest on the website, similar to Relay (https://facebook.github.io/relay/en/versions.html). They have docs only for master/latest/classic. Other projects (like https://github.com/facebook/react-native-website) already have their docs in its own repo. |
Codecov Report
@@ Coverage Diff @@
## master #5541 +/- ##
=======================================
Coverage 60.63% 60.63%
=======================================
Files 213 213
Lines 7313 7313
Branches 3 4 +1
=======================================
Hits 4434 4434
Misses 2878 2878
Partials 1 1 Continue to review full report at Codecov.
|
@thymikee is this GTG? |
6036226
to
6bd9618
Compare
Looks good. Next step would be to automate it while cutting a release |
Is there any way we can choose not to have a full copy of all docs on the main branch of Jest? Like, is there any way to keep it only in gh-pages or a docs branch? |
@ericnakagawa can you shed some light on that? |
I'll merge it an hope it will make people happy. Thanks so much for working on this! As said, ideally we can move all the copies of old versions in a different branch. |
@cpojer closed instead of merged? |
Oh yeah, oops! |
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
Summary
Hi 👋
This PR adds versioned documentation to the website using Docusaurus' built-in support for it (https://docusaurus.io/docs/en/versioning.html). Current docs on the website are
master
only which may cause confusion about what's available at that time (see #5190).I adjusted
pages/en/versions.js
to have correct links to latest/master/past versions along with brief descriptions for each of them.I also added a link to the release notes of the latest version pointing to
CHANGELOG.md
, and a link to the source code for the latest (master) version. I looked at a few other projects that use this feature and how they customized that page, e.g. https://facebook.github.io/relay/en/versions.html.Notes
yarn run version x.x.x
inside the website's folder to generate docs for that version. I couldn't figure out if this is automated or manual. Should I document it somewhere? Possibly add it to a publish script?master
or earlier versions can be accessed from the versions page.docs
folder and sidebar files that differ from those of the latest version will get copied each time a new version is specified (see https://docusaurus.io/docs/en/versioning.html#fallback-functionality).Test plan
No changes at all