chore(docs): improve version picker #15385

petebacondarwin · 2016-11-10T21:58:00Z

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

chore

What is the current behavior? (You can also link to an open issue here)

Versions in the version picker are hard-coded into each build
This means that newer versions are never shown in older versions of the docs

What is the new behavior (if this is a feature change)?

Now the version information has split into the current and the list of all versions.
In the production deployment the version list is now read from the snapshot build, so we always
get the latest list.

Does this PR introduce a breaking change?

No

Please check if the PR fulfills these requirements

The commit message follows our guidelines: https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-message-format
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

Other information:

Replaces #15381

petebacondarwin · 2016-11-10T21:59:55Z

docs/config/services/deployments/production.js

@@ -39,7 +39,8 @@ module.exports = function productionDeployment(getVersion) {
      'components/lunr.js-' + getVersion('lunr.js') + '/lunr.min.js',
      'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js',
      'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js',
-      'js/versions-data.js',
+      'js/version-data.js',
+      'https://code.angularjs.org/snapshot/docs/js/versions-data.js',


note that in production we read the list from snapshot
otherwise we just use the local

This will require some CORS setup on code.angularjs.org I think

actually no it won't because we are loading via a script not XHR

petebacondarwin · 2016-11-14T08:23:05Z

We could change the docs apps for most releases on code.angularjs.org to use this same code.

Narretz

A few minor things that shold be clarified, otherwise I really like the solution.

Narretz · 2016-11-14T13:32:34Z

Gruntfile.js

@@ -346,7 +346,7 @@ module.exports = function(grunt) {

  grunt.registerTask('minify', ['bower', 'clean', 'build', 'minall']);
  grunt.registerTask('webserver', ['connect:devserver']);
-  grunt.registerTask('package', ['bower', 'validate-angular-files', 'clean', 'buildall', 'minall', 'collect-errors', 'docs', 'copy', 'write', 'compress']);
+  grunt.registerTask('package', ['bower', 'validate-angular-files', 'clean', 'buildall', 'minall', 'collect-errors', 'write', 'docs', 'copy', 'compress']);


Why this change?

This is because the version.json file is generated by the write grunt task. So we need it to run before the docs task, which now relies upon it.

Narretz · 2016-11-14T13:36:39Z

docs/config/processors/versions-data.js

+      var output = exec('npm info angular versions --json', { silent: true }).stdout;
+      var versions = processAllVersionsResponse(JSON.parse(output));
+
+      docs.push({


Can we call this current-version-data? This makes it clearer what's the difference from version-data.js

OK, I agree that the visual difference between versions and version is not that obvious

Narretz · 2016-11-14T14:19:05Z

docs/config/processors/versions-data.js

    $process: function(docs) {

-      var versionDoc = {
+      var blacklist = this.blacklist;


What's the meaning of the blacklist? Can you please add a comment?

OK. The main reason was that we appear to have npm published a random rogue release, 1.3.4-build.3588, which does not have an associated folder on code.angularjs.org

gkalpak · 2016-11-14T23:07:25Z

docs/config/processors/versions-data.js

+              }
+              return version;
+          })
+          .filter(function(version) {


AFAICT, filtering after having populated latestMap, will allow 0.x versions to appear in the "Latest" group of the dropdown. The filtering should be done before populating ``latestMap`.

I can't reproduce this locally. It also looks like we don't include any 0.x versions at all.

I didn't try it locally, but from looking at the code I assumed that 0.x versions would be shown in the "Latest" group. Are you sure they are not there (only in the "Latest" group though).

gkalpak · 2016-11-15T08:38:25Z

Not directly related to this PR, but close enough:
I miss showing the build number in the version picker for snapshot releases.

Narretz · 2016-11-15T08:55:16Z

The build number is shown on the api docs home page. Why do you want to have it in the picker?

gkalpak · 2016-11-15T09:47:08Z

Convenience :) It makes it easy to see when refreshing the page gets you a newer build.
It's probably only useful to me, not to our users :)

petebacondarwin · 2016-11-15T09:51:41Z

I think we should display the build number of the docs somewhere on the page. Perhaps near the bottom?

Closes angular#15385

Narretz · 2016-11-15T10:42:52Z

The build number is displayed in the footer. :D On docs/api (main page), then it's also in the first paragraph.

gkalpak · 2016-11-15T11:02:34Z

Right. But you have to scroll all the way down to see the footer 😃
Anyway, it is probably not worth making it more convenient for me/us, if it is something that most users don't care about. The info is there if someone needs it (even if they have to scroll 😃).

gkalpak · 2016-11-15T11:18:10Z

LGTM as long as Travis is happy.

petebacondarwin · 2016-11-15T11:56:56Z

Travis is not happy but it is an east fix

petebacondarwin · 2016-11-15T12:11:45Z

Travis is now happy - after a copied the all-versions.js file onto the snapshot :-)

Closes #15385

Closes angular#15385

Closes #15385

petebacondarwin · 2016-11-28T10:32:11Z

See 4836278

Closes angular#15385

petebacondarwin added needs: review type: chore type: docs labels Nov 10, 2016

petebacondarwin added this to the 1.6.x (post 1.6.0) milestone Nov 10, 2016

googlebot added the cla: yes label Nov 10, 2016

petebacondarwin mentioned this pull request Nov 10, 2016

chore(docs): improve version picker #15381

Closed

3 tasks

petebacondarwin commented Nov 10, 2016

View reviewed changes

petebacondarwin force-pushed the docs-version-picker-2 branch 5 times, most recently from fe01070 to 4c41ec7 Compare November 11, 2016 20:35

Narretz suggested changes Nov 14, 2016

View reviewed changes

gkalpak suggested changes Nov 14, 2016

View reviewed changes

chore(package.json): update to latest version of shelljs

0f45ade

petebacondarwin force-pushed the docs-version-picker-2 branch from 4c41ec7 to 0f2f08b Compare November 15, 2016 10:34

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 15, 2016

chore(docs): improve version picker

0f2f08b

Closes angular#15385

chore(docs): improve version picker

ce49edc

Closes angular#15385

petebacondarwin force-pushed the docs-version-picker-2 branch from 0f2f08b to ce49edc Compare November 15, 2016 10:40

gkalpak approved these changes Nov 15, 2016

View reviewed changes

petebacondarwin merged commit ce49edc into angular:master Nov 15, 2016

petebacondarwin added a commit that referenced this pull request Nov 15, 2016

chore(docs): improve version picker

5e914a5

Closes #15385

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): improve version picker

d72385a

Closes angular#15385

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): improve version picker

d44abf4

Closes angular#15385

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): improve version picker

eb1dd34

Closes angular#15385

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): improve version picker

b97ff9a

Closes angular#15385

petebacondarwin added a commit to petebacondarwin/angular.js that referenced this pull request Nov 21, 2016

chore(docs): improve version picker

ddbbe51

Closes angular#15385

petebacondarwin added a commit that referenced this pull request Nov 23, 2016

chore(docs): improve version picker

c607ea5

Closes #15385

petebacondarwin added a commit that referenced this pull request Nov 24, 2016

chore(docs): improve version picker

4836278

Closes #15385

ellimist pushed a commit to ellimist/angular.js that referenced this pull request Mar 15, 2017

chore(docs): improve version picker

80feace

Closes angular#15385

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(docs): improve version picker #15385

chore(docs): improve version picker #15385

petebacondarwin commented Nov 10, 2016

petebacondarwin Nov 10, 2016

petebacondarwin Nov 12, 2016

petebacondarwin Nov 14, 2016

petebacondarwin commented Nov 14, 2016

Narretz left a comment

Narretz Nov 14, 2016

petebacondarwin Nov 14, 2016

Narretz Nov 14, 2016

petebacondarwin Nov 14, 2016 •

edited

Loading

Narretz Nov 14, 2016

petebacondarwin Nov 14, 2016

gkalpak Nov 14, 2016

Narretz Nov 15, 2016

gkalpak Nov 15, 2016

gkalpak commented Nov 15, 2016

Narretz commented Nov 15, 2016

gkalpak commented Nov 15, 2016

petebacondarwin commented Nov 15, 2016

Narretz commented Nov 15, 2016 •

edited

Loading

gkalpak commented Nov 15, 2016

gkalpak commented Nov 15, 2016

petebacondarwin commented Nov 15, 2016

petebacondarwin commented Nov 15, 2016

petebacondarwin commented Nov 28, 2016

chore(docs): improve version picker #15385

chore(docs): improve version picker #15385

Conversation

petebacondarwin commented Nov 10, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petebacondarwin commented Nov 14, 2016

Narretz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

petebacondarwin Nov 14, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gkalpak commented Nov 15, 2016

Narretz commented Nov 15, 2016

gkalpak commented Nov 15, 2016

petebacondarwin commented Nov 15, 2016

Narretz commented Nov 15, 2016 • edited Loading

gkalpak commented Nov 15, 2016

gkalpak commented Nov 15, 2016

petebacondarwin commented Nov 15, 2016

petebacondarwin commented Nov 15, 2016

petebacondarwin commented Nov 28, 2016

petebacondarwin Nov 14, 2016 •

edited

Loading

Narretz commented Nov 15, 2016 •

edited

Loading