Add an option to switch versions of the docs

[mischah]

Hej,

I would love to add a version switcher for the yeoman docs: https://github.com/yeoman/yeoman/issues/1485

Proposal

Add a versionSwitcher property into the template settings like:

"templates": {
    "name": "Doc Template",
    "footerText": "NHN Entertainment Frontend Development Lab",
    "versionSwitcher": true
  }

If templates.versionSwitcher is true and we have the version number from the package.jsonvia opts.package we replace the version number in the left column with a select element to switch versions.

Mockup

[mischah]

Is that a welcoming feature? I would love to create a PR for that.

[minkyu-yi]

Yeah, so Good~ But I think, I'm worried about that if the page is lower version, it can't change to the upper version.

If the latest version is 2.1.0, will be possible the some issues like the following. 2.1.0 --> 1.1.0 -(x)->2.1.0

Any ideas about that?

[mischah]

But I think, I'm worried about that if the page is lower version, it can't change to the upper version.

Good point. Haven’t thought about that :hushed: Just did some quick research and it seems to be a »known issue« with version switchers in API docs.

Angular docs for instance ignoring that: https://code.angularjs.org/1.5.7/docs/api

But there are API docs which handle that properly, like Lodash for example: https://lodash.com/docs

But most of the API docs simply don’t offer a version switcher:

• https://nodejs.org/dist/latest-v7.x/docs/api
• http://momentjs.com/docs/
• http://underscorejs.org/
• http://mochajs.org/
• http://chaijs.com/api/
• http://emberjs.com/api/
• http://api.jquery.com/
• https://theintern.github.io/intern
• … etc.

Options

So I see the following options:

1. Ignore it

Like Angular does.

2. Parse and update the old versions

… and add the <option> elements for newer versions.

Example: After generating the docs of 1.0.4:

.
└── doc
    ├── 1.0.2
    ├── 1.0.3
    └── 1.0.4

We immediately parse the HTML files in all other directories and replace naviagtion.

This is just an idea. Would need to explore if this is possible.

3. Generate the docs in an Iframe

So the version switcher would be placed on top of the page and exists only 1 time. Visually similiar like Lodash handles it: https://lodash.com/docs/4.16.6

Which end up in the following structure:

.
└── doc
    ├── index.html // holds the version switcher and the iframe
    ├── 1.0.2      // loaded into the iframe
    ├── 1.0.3      // loaded into the iframe
    └── 1.0.4      // loaded into the iframe

Also just an idea. Would need to explore if this is possible.

[mischah]

My personal opinion: I think we might start with »1. Ignore it« as a quick feature and could check the other options afterwards.

[minkyu-yi]

WOW!! Awesome!

I think the third is the best solution for the wide-range and when develop the third, our template does not need additional feature.

1 - directories

root or docs directory
 ├── index.html // This file is not depend on jsdoc-template
 ├── 1.0.0      // generated doc directory
 ├── 1.1.0      // generated doc directory
 ├── 1.2.0      // generated doc directory
 └── 2.0.0      // generated doc directory

2 - Example index.html

...

<select id="version">
  <option value="" disabled="">Version</option>
  <option value="2.0.0" selected="">2.0.0</option>
  <option value="1.2.0">1.2.0</option>
  <option value="1.1.0">1.1.0</option>
  <option value="1.0.0">1.0.0</option>
</select>
<iframe id="doc-frame" src='./2.0.0'></iframe>

<script>
var $docFrame = $('#doc-frame');
$('#version').change(function(event) {
    $docFrame.attr('src', './' + event.target.value);
});
</script>

How about this?

[minkyu-yi]

If our template should have the version switcher, we can think an another solution and start with the first-ignore as a quick feature.

1 - directories

root or docs directory
 ├── versionSwicher.data.js // This file has all url of versions
 ├── 1.0.2      // generated doc directory
 ├── 1.0.3      // generated doc directory
 └── 1.0.4      // generated doc directory

2 - versionSwitcher.data.js

const __versionSwitcherData = {
    '1.0.2': 'url/1.0.2',
    '1.0.3': 'url/1.0.3',
    '1.0.4': 'url/1.0.4'
};

3 - index.html in generated doc directory == layout.tmpl

....add tags for version switcher

<script src='../versionSwitcher.data.js'></script>
<script>
function addToVersionSwitcher(version, url) {
   //... code
}
_.each(__versionSwitcherData, addToVersionSwitcher);
</script>

And how about this?

[mischah]

Hej 이민규,

I just opened a PR for option 1. Had that already in work before your answers.

But, I totally agree with you. Option 3 seems to be the cleanest.

Take your time to review #9 and decide if you would like to merge and release it as the first implementation of the version switcher.

[minkyu-yi]

Yeah~! good. Our team and I decided the option 1. It will be releaseed 1.1.0 with your pr. thank you~!

[201flaviosilva]

Hey there, I'm a little late on this conversation, but has this been implemented? 😅 I really need this feature :)

(There is any example?)