version docs (fixes #121) #245

ngokevin · 2016-05-16T22:52:57Z

Problem is we are currently only showing master/ docs on aframe.io which gives people incorrect information as most users are on 0.2.0. Default to 0.2.0 docs and add a dropdown to switch between them. The only con is not being able to upstream typo fixes in the 0.2.0 docs since that would involve cherry-picking and too much effort. But at least we show the shiny master/ version

Use multidep to install multiple versions of A-Frame.
docs/0.2.0 symbolic links to multidep/. docs/master symbolic links to node_modules/.
Paths changed from docs/<docpath> to docs/<VERSION>/<docpath>. Include redirects
Filter docs in EJS to the currently-viewing version
dropdown to switch between versions
set currently-viewed version to set correct filter
Import 0.1.0 docs
Automatically have all doc links go directly to the first page of the docs rather than rely on the redirect
Smart sort doc nav

Other:

Defaults to stable/current version (which is 0.2.0 right now).
Simplify redirect data structure

cvan · 2016-05-17T06:59:18Z

README.md

@@ -30,7 +32,12 @@ And then link `aframe-site` to `aframe`:
    cd aframe-site
    npm link aframe

-Then the documentation will update as you work on them from the A-Frame repository. This works because we have pointed the A-Frame site, via a soft symbolic link, to the documentation installed in `node_modules/aframe/docs/`.
+Then the `master` documentation will update as you work on them from the
+A-Frame repository. This works because we have pointed the A-Frame site, via a


link to repo?

anything else for this PR?

I'll review it thoroughly tomorrow. thanks for this.

cvan · 2016-05-20T19:57:48Z

is there any way we can test with writing new docs for new versions but hide that version until it's ready and released? maybe some local dev flag. we should have one / be able to add one easily with hexo plugins (maybe browsersync).

ngokevin · 2016-05-20T20:40:50Z

OK, I'll try

ngokevin · 2016-05-21T05:27:35Z

Actually, the new docs are just master docs. They won't show by default like they are now, and there will be a dropdown in the versions dropdown to view master docs.

ngokevin · 2016-05-24T19:57:54Z

^ So nothing else needed to be done so far.

cvan · 2016-05-24T21:47:45Z

package.json

    "generate": "hexo generate",
    "predeploy": "hexo clean",
-    "deploy": "hexo deploy && open 'https://aframe.io/'",
+    "pretest": "multidep multidep.json",


this was not obvious to me that I had to run npm run pretest before the symlinks would work. perhaps call this too w/ postinstall.

oops, i was following a guide that was doing this for testing. thanks for catching

cvan · 2016-05-24T22:02:21Z

load http://localhost:4000/docs/master/components/canvas.html
hover over "Core" heading link in the sidebar
notice the URL is http://localhost:4000/docs/core/ but then redirects to http://localhost:4000/docs/master/core/

can we fix those URL routes so we're not redirecting? because we don't have server-side redirects for any of these (yet, though I can manually add them all to our CloudFlare Page Rules), this is actually quite slow - even locally.

cvan · 2016-05-24T22:04:35Z

themes/aframe/layout/docs.ejs

+          <a href="<%- page_url(page.path) %>" class="guide-link guide-link-left">
+            ← <%= page.title %>
+          </a><
+        /span>


this newline before actually breaks things:

cvan · 2016-05-24T22:10:54Z

looking great! let me know when to take another look

ngokevin · 2016-05-26T21:28:27Z

OK, hope I got everything.

Old pre-versioned doc links (e.g.,/docs/guide/ will route to 0.2.0 docs forever in case those pages disappear in the future).
To solve the sidebar doc link confusion going to 0.2.0 when you may be on another version, I replaced the Guide/Install links with one Docs link that is active/disabled whenever you are browsing the docs. Then all documentation navigation is done through the docs nav.

ngokevin · 2016-05-31T17:28:43Z

@cvan ready

ngokevin · 2016-05-31T22:18:06Z

At your earliest convenience! Somewhat antsy about this one since the documentation is wrong for 0.2.0 and people have been running into the same breaking changes and getting confused (e.g., cursor- prefix added).

cvan · 2016-05-31T22:23:20Z

no worries - testing now, will provide feedback momentarily

cvan · 2016-05-31T22:58:13Z

scripts/helpers.js

+  var versions = aframeVersions.slice(0);
+  var currentVersionIndex = versions.indexOf(currentVersion);
+  versions.splice(currentVersionIndex, 1);
+  return [currentVersion, MASTER].concat(versions);


it seems odd to me that MASTER appears below not above 0.2.0? don't we want to sort chronologically?

can we change that?

OK, changed.

previous reasoning was in order of relevance, but yeah it was weird.

cvan · 2016-05-31T23:42:15Z

scripts/redirects.js

+    ['docs/core/templates.html', 'https://github.com/ngokevin/aframe-template-component'],
+    ['docs/guide/cameras-and-lights.html', 'docs/guide/building-a-basic-scene.html'],
+    ['docs/guide/entering-vr.html', 'http://mozvr.com/#start'],
+    ['docs/guide/installation.html', 'docs/guide/getting-started.html'],


interesting bug:

http://localhost:4000/docs/0.1.0/guide/installation.html can be loaded. it's now http://localhost:4000/docs/0.1.0/guide/getting-started.html.

If I understand your point correctly, this redirect was before we were versioning. We wanted to redirect docs/guide/installation (0.1.0) to docs/guide/getting-started.html (0.2.0). Now that we have a version prefix, we don't necessarily have to redirect the 0.1.0/guide/installation.html since that page exists now.

I think I will version the destination of these redirects though so that we're not constantly updating these on each release.

I versioned the old redirects: https://github.com/aframevr/aframe-site/pull/245/files#diff-f38517d4dd3fc581f64643b3dd59e408R20

It's a bit confusing to think about, but I believe this makes sense, and users with old links should end up in the appropriate places.

which of the following should docs/guide/installation.html redirect to?

docs/guide/getting-started.html

docs/guide/0.1.0/installation.html

docs/guide/0.1.0/getting-started.html

docs/guide/0.2.0/installation.html

docs/guide/0.2.0/getting-started.html

I chose docs/0.2.0/guide/getting-started.html to keep things the way they are currently.

docs/0.1.0/guide/installation.html is more accurate. But not sure about having redirected to 0.2.0 and then suddenly redirecting it back to 0.1.0.

cvan · 2016-06-01T00:07:40Z

I just pulled, and http://localhost:4000/docs/ / http://localhost:4000/docs/0.2.0/guide/ no longer works

ngokevin · 2016-06-01T01:26:55Z

^ Did you run the new postinstall?

Updated everything, last thing I need to do is remove unnecessary redirects by assigning a index page front matter variable so we know what is the first page of the docs, and then polyfilling that for old versions that won't have that front matter.

ngokevin · 2016-06-01T01:33:30Z

Actually, I can filter order: 1 / section_order: 1 to determine the first page of the docs :)

ngokevin · 2016-06-01T04:49:11Z

OK, all complete. Most recent commit has changes for deducing the first page of the docs.

ngokevin · 2016-06-02T00:31:44Z

🐛

cvan · 2016-06-02T00:39:12Z

🐹 👀

cvan · 2016-06-02T20:45:01Z

looks like "Install" nav link is removed. IMO, we should have a very prominent "Install" or "Download" link:

will file separately.

filed #268

cvan · 2016-06-02T20:57:03Z

r+ this all looks great to me.

🎉 fantastic work, man!

ngokevin · 2016-06-02T20:57:50Z

re: installed, Agreed. I don't think it was prominent where it was anyways.

ngokevin · 2016-06-02T20:57:59Z

Thanks for the detailed review!

ngokevin changed the title ~~[WIP] version docs~~ version docs (fixes #121) May 17, 2016

ngokevin force-pushed the vdocs branch 2 times, most recently from f55bde7 to dd36af0 Compare May 17, 2016 00:30

ngokevin referenced this pull request in joliss/node-multidep May 17, 2016

Fix recommended npm hook

91aedc8

ngokevin added the needs review label May 17, 2016

cvan reviewed May 17, 2016
View reviewed changes

cvan reviewed May 24, 2016
View reviewed changes

cvan added needs changes and removed needs review labels May 24, 2016

ngokevin force-pushed the vdocs branch from 520266c to e2edd6c Compare May 26, 2016 21:27

ngokevin added needs review and removed needs changes labels May 26, 2016

ngokevin force-pushed the vdocs branch from 52c25de to 7cb7d92 Compare May 31, 2016 22:06

cvan reviewed May 31, 2016
View reviewed changes

ngokevin force-pushed the vdocs branch 2 times, most recently from 5fb670d to 10f5429 Compare May 31, 2016 23:38

cvan reviewed May 31, 2016
View reviewed changes

cvan added needs changes and removed needs review labels Jun 1, 2016

ngokevin added 3 commits May 31, 2016 21:46

version the docs (fixes aframevr#121)

ff2d95c

remove need for manual ordering

e34d1d7

calculate the first page of the docs, prevent doc redirects

86cfc99

ngokevin force-pushed the vdocs branch from 1568720 to 86cfc99 Compare June 1, 2016 04:47

ngokevin added needs review and removed needs changes labels Jun 1, 2016

cvan removed the needs review label Jun 2, 2016

cvan assigned ngokevin Jun 2, 2016

ngokevin merged commit d7f4f9a into aframevr:master Jun 2, 2016

ngokevin mentioned this pull request Jun 3, 2016

A Week of A-Frame 16 #256

Closed

This pull request was closed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

version docs (fixes #121) #245

version docs (fixes #121) #245

ngokevin commented May 16, 2016 •

edited

Loading

cvan May 17, 2016

ngokevin May 18, 2016

cvan May 18, 2016

cvan commented May 20, 2016

ngokevin commented May 20, 2016

ngokevin commented May 21, 2016

ngokevin commented May 24, 2016

cvan May 24, 2016

ngokevin May 26, 2016

cvan commented May 24, 2016

cvan May 24, 2016

cvan commented May 24, 2016

ngokevin commented May 26, 2016

ngokevin commented May 31, 2016

ngokevin commented May 31, 2016

cvan commented May 31, 2016

cvan May 31, 2016

ngokevin May 31, 2016

cvan May 31, 2016 •

edited

Loading

ngokevin May 31, 2016

ngokevin May 31, 2016

cvan May 31, 2016

ngokevin Jun 1, 2016 •

edited

Loading

cvan commented Jun 1, 2016

ngokevin commented Jun 1, 2016

ngokevin commented Jun 1, 2016 •

edited

Loading

ngokevin commented Jun 1, 2016

ngokevin commented Jun 2, 2016

cvan commented Jun 2, 2016

cvan commented Jun 2, 2016 •

edited

Loading

cvan commented Jun 2, 2016

ngokevin commented Jun 2, 2016

ngokevin commented Jun 2, 2016

version docs (fixes #121) #245

version docs (fixes #121) #245

Conversation

ngokevin commented May 16, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cvan commented May 20, 2016

ngokevin commented May 20, 2016

ngokevin commented May 21, 2016

ngokevin commented May 24, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cvan commented May 24, 2016

Choose a reason for hiding this comment

cvan commented May 24, 2016

ngokevin commented May 26, 2016

ngokevin commented May 31, 2016

ngokevin commented May 31, 2016

cvan commented May 31, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cvan May 31, 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

ngokevin Jun 1, 2016 • edited Loading

Choose a reason for hiding this comment

cvan commented Jun 1, 2016

ngokevin commented Jun 1, 2016

ngokevin commented Jun 1, 2016 • edited Loading

ngokevin commented Jun 1, 2016

ngokevin commented Jun 2, 2016

cvan commented Jun 2, 2016

cvan commented Jun 2, 2016 • edited Loading

cvan commented Jun 2, 2016

ngokevin commented Jun 2, 2016

ngokevin commented Jun 2, 2016

ngokevin commented May 16, 2016 •

edited

Loading

cvan May 31, 2016 •

edited

Loading

ngokevin Jun 1, 2016 •

edited

Loading

ngokevin commented Jun 1, 2016 •

edited

Loading

cvan commented Jun 2, 2016 •

edited

Loading