tui.jsdoc-template feat: version switcher

Hej, here’s the implementation of option 3 of the version switcher as proposed in #5.

Must say that I prefer it over the implementation of option 1 in #9

Pros:

You can switch from older version to newer
Less changes in publish.js
- Makes it easier to integrate future changes from JSDocs default template

Cons:

We are loosing the custom page titles from the docs
- Cause we only see the output from the <title> Element of the page holding that iFrame
We are loosing bookmarkability and deeplinking to subpages

Closes #5

Nov 18 '16 00:11 mischah

Ready to review :octocat:

Nov 18 '16 01:11 mischah

v1 0 4

Nov 18 '16 01:11 mischah

`option3` vs `option1`

Must say that I prefer it over the implementation of option 1 in #9

~~Yeah, I prefer the option1 too. I was just busy for a while and could not see the #9.~~ ~~However, this option3 is good too as the option1.~~ ~~So I think the option3 should be pended for a while and reopen the #9.~~ ~~(Sorry too late,, I should have seen the #9 early)~~

--> (update) I misunderstood the above sentence 😖. Ok. This option3 will be a good feature. Thanks~

Another proposal

Readme.md - line 67

The version switcher gets the versions via Git tags. But JSDoc only generates the current sources. So keep in mind that you have to generate the docs for each tag. Otherwise switching versions will lead to 404 errors.

How about the ignore option in versionSwitcher? Bc the patch versions or build versions don't need to generate new docs.

If agree, at least how about adding a [string|array] values to ignore option?

In configuration,

--- no ignore.

"versionSwitcher": "true"

--- ignore some versions.

"versionSwitcher": {
    "ignore": "minor"
}

or

"versionSwitcher": {
    "ignore": "patch"
}

or

"versionSwitcher": {
    "ignore": ["1.0.1", "1.0.1+12312", "..."]
}

~~If you are busy, I can take over this based on #9 🙂.~~

Nov 21 '16 13:11 minkyu-yi

I think this approach is better that #9 See pro arguments.

Do you agree? In this case I would implement the ignore option 😊

Nov 21 '16 15:11 mischah

I really like the idea of the ignore option.

Plus having the possibility to ignore patch versions or specific versions.

But it would be more useful to accepts semver syntax and ignore version levels like this

"versionSwitcher": {
    "versions": [">=2.x"]
}

This would result in having all versions up from 2.0.0. See npm semver calculator

Or

"versionSwitcher": {
    "versions": [">=2.x"],
    "excludeLevel": "patch"
}

This would result in having all versions up from 2.0.0 excluding patch level releases.

Nov 21 '16 15:11 mischah

Awesome~ I agree this semver-syntax + excludeLevel option. 👍

Nov 22 '16 01:11 minkyu-yi

Guess I’m done with that :octocat:

Anyone wants to review? 😗

Nov 27 '16 00:11 mischah

Hej @minkyu-yi,

any idea when to land this approximately?

Sorry, I don’t wanna put any pressure on you but I’m so excited to use that template for the Yeoman docs 😗

Nov 29 '16 15:11 mischah

@mischah

Yeah, I hope to release no later than next week. Sorry for the delay.

Dec 02 '16 02:12 minkyu-yi

👌 Thanks for the info.

Dec 02 '16 08:12 mischah

Hej @mischah

Thanks for the pr. And I found a problem about url. (may be relative to the your concern.)

We could access a specific method, class, etc from url without the iframe-version-switcher.

But we can not access from url with the iframe-version-switcher.

This problem arises from iframe. Sorry, I didn't realize this problem in advance.

So I propose the version-switcher form(<form class="form-inline version-switcher">) in layout.tmpl instead of iframe.

This form rendered in layout.tmpl like below if the version-switcher option is truthy.

<body>
  <?js if(versionSwitcher) { ?>
      <header>
          <form class="form-inline version-switcher">
              <div class="form-group">
                  <label for="selectVersion">Version:</label>
                  <select id="selectVersion" class="form-control"></select>
              </div>
          </form>
      </header>
  <?js } ?>

  ...left-navigation,
  ...main
  ...footer
</body>

Or any ideas to solve this problem? I'm looking forward to your opinion.

Dec 04 '16 07:12 minkyu-yi

This problem arises from iframe. Sorry, I didn't realize this problem in advance.

No problem. Me neither. Just updated the initial PR description.

So. Yes. Native browser deeplinking and bookmarkability is another thing we lose with the iFrame approach. But it has other pros. See first PR description. ⬆️

Must say that I don’t want to trash the iFrame approach because of its pros.

Possible solution

With https://github.com/nhnent/tui.jsdoc-template/pull/11/commits/f46954c888a3025e49d07b1c0ad0a9d7e31d21c9 I made it possible to link to older versions.

I could try to extend this functionality to:

Adress bookmarkability:
- Update the iFrame URL (visible in the adress bar) with every click inside the iFrame
Adress deeplinking:
- Pass URL options from iFrame URL (visible in the adress bar) to the iframe src on page load

Is this something you would accept as solution?

Dec 05 '16 13:12 mischah

Yeah~!😀

In this problem, with your solutions, using the iframe is not a problem. We can sync parent url and iframe url with using your solutions.

So we can share a specific url with others for seeing the same page within version-switcher.

Is it right? I think it would be a really useful feature.

I appreciate your help.

Dec 05 '16 13:12 minkyu-yi

So we can share a specific url with others for seeing the same page within version-switcher.

Yeah. Thats how it should work. Can’t promise anything for now, though. But I would like to give it a try.

Back to the example you posted.

URL without version switcher:

http://localhost:8080/tui.component.BaseChild.html#getDatum

URL with version switcher enabled:

http://localhost:8080?v=1.3.0&page=tui.component.BaseChild.html#getDatum

or similar

Im not quite sure how to implement that. I possibly could use the HTML5 history API. But this is only supported by IE10 and above. Do you have any problem if this won’t work with IE9 and below?

Dec 05 '16 14:12 mischah

I think most use cases of jsdoc-template are on modern browsers. So the version-switcher doesn't need to support old browsers.🙂

Dec 07 '16 06:12 minkyu-yi

@mischah Hi. long time no see. Soon it is time to minor update for other features. So, I just wonder when we get this feature? I'm looking forward your comment.

Thank you :)

Jan 13 '17 08:01 minkyu-yi

Thanks for pinging me. I’m on parental leave for the next 3 weeks and quite busy with parenting 😄

I picked up a newborn and the mother from hospital the day before yesterday plus I need to take care of my 2 year old son. Hope that things are getting more relaxed next week. But I can't promise anything by now. Sorry 🙈

Jan 13 '17 17:01 mischah

Oh, I see. Congratulations on your newborn 🎉 I hope you get more relaxed, too.

Thank you!

Jan 15 '17 07:01 minkyu-yi

Hej, it’s been almost a year since I started working on this 🙈

Just wanna say thank you for keeping this open. I guess finally find time to finish this next month 😘

Nov 09 '17 09:11 mischah

@mischah bump ;)

Jul 08 '18 03:07 alex-taxiera

tui.jsdoc-template tui.jsdoc-template copied to clipboard

feat: version switcher

option3 vs option1

Another proposal

Possible solution

tui.jsdoc-template
tui.jsdoc-template copied to clipboard

`option3` vs `option1`