add versioned documentation to the website #5541

ronami · 2018-02-13T00:40:58Z

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

When a new version is published we should also run 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?
I created documentation for the latest version (v22.2.2), do we plan on going back to past versions and creating docs for them?
Normally the website will show docs for the latest stable version. Docs for master or earlier versions can be accessed from the versions page.
This is a fairly large PR (in terms of lines of code) but only files in the 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

thymikee

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

thymikee · 2018-02-13T07:04:09Z

website/pages/en/versions.js

+            <header className="postHeader">
+              <h2>{siteConfig.title + ' Versions'}</h2>
+            </header>
+            <a name="latest" />


Anchors should have a href attribute, you can use a button instead. Please fix this in other places too,

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.

Ah, this is so wrong. The name attr on anchors is obsolete. They should just use ids. Mind filing an issue or PR fixing that? There's no need to create artificial pseudo anchor too.

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 ids instead.

thymikee · 2018-02-13T07:07:56Z

website/versioned_docs/version-22.2.2/CLI.md

@@ -0,0 +1,328 @@
+---
+id: version-22.2.2-cli


Can we use just major and minor versions for docs? I'd rather have docs for "Jest 22.2". Patches are for fixes

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.

22.2.X seems reasonable

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?

ronami · 2018-02-13T08:54:58Z

@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-io · 2018-02-13T10:45:21Z

Codecov Report

Merging #5541 into master will not change coverage.
The diff coverage is n/a.

@@           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.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 430aebe...6bd9618. Read the comment docs.

SimenB · 2018-02-17T15:03:31Z

@thymikee is this GTG?

…dant anchors

thymikee · 2018-02-17T16:14:49Z

Looks good. Next step would be to automate it while cutting a release

cpojer · 2018-02-17T16:52:27Z

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?

thymikee · 2018-02-17T16:56:19Z

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?

cpojer · 2018-02-20T21:13:30Z

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.

SimenB · 2018-02-21T06:56:51Z

@cpojer closed instead of merged?

cpojer · 2018-02-21T08:43:45Z

Oh yeah, oops!

github-actions · 2021-05-12T20:06:47Z

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.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.

facebook-github-bot added the CLA Signed ✔️ label Feb 13, 2018

thymikee requested changes Feb 13, 2018

View reviewed changes

ronami added 5 commits February 17, 2018 17:08

add versioned documentation to the website

caaeacf

add changelog for versioned documentation

205d221

exclude versioned docs from specific lint rules

40bd480

use id attribute instead of name for in page anchors and remove redun…

8aaa211

…dant anchors

re-create docs for v22.3 with latest changes from master

6bd9618

ronami force-pushed the add-versioned-documentation branch from 6036226 to 6bd9618 Compare February 17, 2018 15:36

thymikee approved these changes Feb 17, 2018

View reviewed changes

cpojer closed this Feb 20, 2018

SimenB reopened this Feb 21, 2018

cpojer merged commit 6ab04b7 into jestjs:master Feb 21, 2018

ronami deleted the add-versioned-documentation branch February 21, 2018 08:48

SimenB mentioned this pull request Mar 20, 2018

404 Not Found for docs in other translation #5824

Closed

github-actions bot locked as resolved and limited conversation to collaborators May 12, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add versioned documentation to the website #5541

add versioned documentation to the website #5541

ronami commented Feb 13, 2018 •

edited

Loading

thymikee left a comment

thymikee Feb 13, 2018

ronami Feb 13, 2018

thymikee Feb 13, 2018

ronami Feb 13, 2018

thymikee Feb 13, 2018

ronami Feb 13, 2018 •

edited

Loading

SimenB Feb 13, 2018

ronami Feb 13, 2018

ronami commented Feb 13, 2018 •

edited

Loading

codecov-io commented Feb 13, 2018 •

edited

Loading

SimenB commented Feb 17, 2018

thymikee commented Feb 17, 2018

cpojer commented Feb 17, 2018

thymikee commented Feb 17, 2018

cpojer commented Feb 20, 2018

SimenB commented Feb 21, 2018

cpojer commented Feb 21, 2018

github-actions bot commented May 12, 2021

add versioned documentation to the website #5541

add versioned documentation to the website #5541

Conversation

ronami commented Feb 13, 2018 • edited Loading

Summary

Notes

Test plan

thymikee left a comment

Choose a reason for hiding this comment

thymikee Feb 13, 2018

Choose a reason for hiding this comment

ronami Feb 13, 2018

Choose a reason for hiding this comment

thymikee Feb 13, 2018

Choose a reason for hiding this comment

ronami Feb 13, 2018

Choose a reason for hiding this comment

thymikee Feb 13, 2018

Choose a reason for hiding this comment

ronami Feb 13, 2018 • edited Loading

Choose a reason for hiding this comment

SimenB Feb 13, 2018

Choose a reason for hiding this comment

ronami Feb 13, 2018

Choose a reason for hiding this comment

ronami commented Feb 13, 2018 • edited Loading

codecov-io commented Feb 13, 2018 • edited Loading

Codecov Report

SimenB commented Feb 17, 2018

thymikee commented Feb 17, 2018

cpojer commented Feb 17, 2018

thymikee commented Feb 17, 2018

cpojer commented Feb 20, 2018

SimenB commented Feb 21, 2018

cpojer commented Feb 21, 2018

github-actions bot commented May 12, 2021

ronami commented Feb 13, 2018 •

edited

Loading

ronami Feb 13, 2018 •

edited

Loading

ronami commented Feb 13, 2018 •

edited

Loading

codecov-io commented Feb 13, 2018 •

edited

Loading