[Docs] Add versions to docs site #3383

mbrookes · 2016-02-18T21:46:23Z

@callemall/material-ui

Guys, I might be busy this week, but I haven't been completely idle! 😄

WIP but throwing this out for comment. You might find this easier to test if you merge with master temporarily, as the script will bounce you back there; otherwise comment out that line.

You will also need the gh-pages branch from my repo which has all the past versions in it. (I can share the script for building that, but it has no future value).

The script docs/gh-pages-build does the work of adding a new versioned build of the docs site to the gh-pages branch, and updating versions.json which is used for the versions Drop Down Menu (currently in the LeftNav).

When future versions are added, older versions (starting from 0.15.x) will be able to navigate to them, since versions.json is shared across all versions that use it.

To build a new version, you can run the script with npm run gh-pages-build, or just node ./gh-pages-build.js. It takes one argument - a version version number for the build beginning with v.

Feedback appreciated! ☺️

There is also an additional commit, which is a WIP POC for adding version navigation to the older versions.

It occurred to me that we could retrofit a standalone component to the old versions of the docs site by having it in a separate js file with its own render target in the HTML, then being absolutely positioned, somewhere along the top NavBar.

I have updated index.html (only in master, not in the older versions yet), and partially extracted the necessary code for a standalone Versions component. Where I got stuck was with the webpack config; something I know nothing about. I was hoping that if this approach seems viable, one of you guys could take a look and see what's required.

Edit: Should add that I haven't styled the DropDown in the LeftNav to fit - not convinced it looks right there anyway, but it was convenient for testing.

Closes #1986.

newoga · 2016-02-18T22:09:29Z

@mbrookes! 🎉

This looks awesome, I'm going to look more indepth tonight.

It occurred to me that we could retrofit a standalone component to the old versions of the docs site by having it in a separate js file with its own render target in the HTML, then being absolutely positioned, somewhere along the top NavBar.

I think this is a clever idea and worth exploring. 👍

I hope you're enjoying your trip! 😄

mbrookes · 2016-02-18T22:42:08Z

I hope you're enjoying your trip! 😄

Thanks. Work, and nowhere exciting, but got to catch up with some old friends for a couple of hours last night which was great!

I think this is a clever idea and worth exploring. 👍

Glad you like the idea. Wasn't sure how big an overhead it would add though.

newoga · 2016-02-19T08:37:58Z

docs/src/app/versions.jsx

@@ -0,0 +1,83 @@
+import React from 'react';
+import ReactDOM from 'react-dom';


I wonder how far back this will work since pre React 0.14.0 it was React.render instead of ReactDOM.render?

Unless I'm misunderstanding, this is going to import whatever version of React is current when the versions.jsx js is built.

It does make the rather large assumption that it's possible to have two scripts (versions.js and app.js) that are running different versions of React loaded concurrently, and I hadn't researched whether that was realistic. It seems it isn't by default, but there is a hack to enable this: facebook/react#1939 (comment)

The alternative might be to not import React at all in versions.js, and to depend on the version of React loaded by any particular version of the Material-UI demo-site. This assumes that the DropDown and the parts of Material-UI it uses are compatible with the earliest version of React in use.

If neither of those is possible, then the only other option (that uses Material-UI) would be to go back and edit the source for each prior version to add the dropdown using the version of Drop Down Menu, and therefore React, that was current at the time.

I'd rather avoid that if possible (editing the source of all the prior versions), so a native <select> (styled to look as close to Material-UI) and with plain js is the only other option I can think of.

And regardless - while navigating around old versions would be a bonus, in reality if you're using a particular version, you'll navigate to it and stick with it, so I don't think getting this working is a priority for 0.15.0. Having the old version docs available should be enough.

Humm, that sounds far too complicated. What about killing this versions.jsx? Do we need this DropDownMenu for older versions? I don't think so.

Yeah, like I said, it's a nice-to-have. I'll kill it for now. We have more important things to worry about!

newoga · 2016-02-19T08:41:58Z

Thanks. Work, and nowhere exciting, but got to catch up with some old friends for a couple of hours last night which was great!

Nice!

@mbrookes I didn't get to check this PR out and review it as in depth as I wanted to tonight! I got caught up working on another issue 😫. Gonna get some rest now but I'll give this a spin during the day tomorrow.

Initial thought when looking over it:
Do you think it makes sense to add support for all releases including betas/RCs? Also is there a way to build without a version into a HEAD folder so we can eventually be able to see what's in currently in master on material-ui.com?

mbrookes · 2016-02-19T12:11:02Z

Edited:

Do you think it makes sense to add support for all releases including betas/RCs?

I'd thought that we could perhaps add them as non-default options to the menu. But I don't think we should add them for prior releases, and I think we should remove them in the major that the RCs are for.

Also is there a way to build without a version into a HEAD folder so we can eventually be able to see what's in currently in master on material-ui.com?

The script already covers most of what's required, but we would need to watch for changes on github.com, pull updates, and have write access to push to the gh-pages branch on the call-em-all fork.

I wasn't going to tackle that as part of this PR.

oliviertassinari · 2016-02-19T20:21:26Z

docs/src/app/components/AppLeftNav.jsx

@@ -81,6 +114,23 @@ const AppLeftNav = React.createClass({
        <div style={prepareStyles(styles.logo)} onTouchTap={this.handleTouchTapHeader}>
          Material-UI
        </div>
+
+        <DropDownMenu


What about something like this instead?

or

newoga · 2016-02-19T20:38:54Z

The script already covers most of what's required, but we would need to watch for changes on github.com, pull updates, and have write access to push to the gh-pages branch on the call-em-all fork.

I wasn't going to tackle that as part of this PR.

Makes sense, maybe separate we could consider setting up a separate travis build for HEAD docs. That way every time we merge, it can kick of automatically without us watching for changes and commit to gh-pages for us.

mbrookes · 2016-02-20T10:58:22Z

Oh, interesting - I hadn't ever looked at Travis-CI beyond clicking to review failed checks, and kicking myself for forgetting to lint before pushing (again!). 😁

mbrookes · 2016-02-23T18:33:15Z

@callemall/material-ui

Okay - I've added pre-release support. Pre-releases don't get symlinked in the gh-pages branch as the default release, and the dropdown will displaying the first full release as currently selected when on the root version.

The gh-pages-build script also now supports building a HEAD version. It takes care of making sure HEAD is at the top of versions.json when a new versioned release is added, and prunes gh-pages commits so we don't end up with a huge history of HEAD releases.

There's also now a -p option, which will force push gh-pages. In theory we can then use: npm run gh-pages:build HEAD -- -p in a Travis build script that fires when new PRs are merged. It may need an extra line to set an upstream - I wasn't sure how that works with Travis, and the docs are horrible, so I'll leave that to one of you guys who's more familiar with Travis to configure that. Happy to make whatever changes are needed to the build script.

If someone could please take this for a spin? Something like:

git checkout master
git merge gh-pages-build
cd docs
npm run gh-pages:build v0.15.0-alpha.1
npm run gh-pages:build HEAD
npm run gh-pages:build HEAD
npm run gh-pages:build v0.15.0
npm run gh-pages:build HEAD

oliviertassinari · 2016-02-23T19:58:33Z

@mbrookes I have just tried this PR: http://oliviertassinari.github.io/material-ui/v0.15.0/.
I hope this will help 😁.
I may not be using the script correctly. I have run those commands:

npm run gh-pages:build HEAD works fine
npm run gh-pages:build v0.15.0-alpha.1 is throwing this issue
mv build ../v0.15.0-alpha.1
mv: rename build to ../v0.15.0-alpha.1/build: Directory not empty
null
npm run gh-pages:build v0.15.0 erase my previous HEAD folder
The ajax request to get versions.json fails

mbrookes · 2016-02-23T20:07:41Z

Thanks @oliviertassinari - do you still have the console output, and if so, please could you put it in a gist? It will help me see where things are going wrong.

oliviertassinari · 2016-02-23T20:17:29Z

I have started again from a clean git history and a clean folder structure.

npm run gh-pages:build v0.15.0-alpha.1 is working fine
npm run gh-pages:build HEAD fails with:

mv build ../HEAD
git add . && git commit -m 'HEAD'
On branch docs-build
nothing to commit, working directory clean
null

mbrookes · 2016-02-24T00:06:12Z

@oliviertassinari - I'm sorry, I just don't get it. I've been trying to break this for the last four hours without success!

From the message it's as if process.chdir('../'); in between those two commands isn't happening.

Could you perhaps add execho('pwd'); or execho('ls'); after that line and see if it is moving up from docs to the main directory, and that the HEAD directory is there?

Perhaps you could also execho('git status') and see what git thinks has or hasn't changed.

newoga · 2016-02-24T00:41:48Z

I'm going to try this now...

I'm tempted to make @oliviertassinari paint @mbrookes a picture if it works, and @mbrookes remove an unnecessary component if it doesn't. 🎲 🎌

newoga · 2016-02-24T00:44:58Z

Alright I'm running into a separate issue that's probably my fault. Maybe I should paint everyone a picture and get back to work...

mbrookes · 2016-02-24T00:54:44Z

I'm tempted to make @oliviertassinari paint @mbrookes a picture if it works, and @mbrookes remove an unnecessary component if it doesn't.

LOL 😆

newoga · 2016-02-24T00:57:15Z

Okay the results are in!

npm run gh-pages:build HEAD works for me 😄. Not quite sure why @oliviertassinari is having a problem. Maybe node version, os (I'm Mac and 5.1.1)? I did run into another issue when a local gh-pages branch wasn't already pulled. Not quite sure what happened though, I can see if I can reproduce and describe better.

Edit: I'm going to head home now from office, I'll play around with this some more later and provide more constructive feedback. I'm excited to get this finished and merged! Awesome stuff @mbrookes

mbrookes · 2016-02-24T01:05:04Z

Maybe node version

I did wonder, but when I searched, it seemed like process.chdir('../') has been in node for a long time (although I may have been fooled by the version number switcheroo).

I did run into another issue when a local gh-pages branch wasn't already pulled.

I'd say. :) You need gh-pages from my fork for the past versions and syminked current version.

alitaheri · 2016-02-24T06:31:26Z

@oliviertassinari Might that be permission related?

newoga · 2016-02-24T06:45:39Z

ROADMAP.md

@@ -31,11 +31,11 @@ The roadmap is a living document, and it is likely that priorities will change,
 - [ ] [[1321](https://github.com/callemall/material-ui/pull/1321#issuecomment-174108805)] Composable AppBar component.
 - [ ] [[#2493](https://github.com/callemall/material-ui/pull/2493)] New Stepper component.
 - [ ] [[#3132](https://github.com/callemall/material-ui/pull/3132)] Scrollable Tabs.
- [X] [[#3033](https://github.com/callemall/material-ui/pull/3132)] New Subheader component.
+- [x] [[#3033](https://github.com/callemall/material-ui/pull/3132)] New Subheader component.


I've been meaning to open a PR for this but since you're editing this line anyway, could you update the link to the right PR? 3132 -> 3133? Technically some of the links above it are wrong too so we could also just fix this later/separately...

newoga · 2016-02-24T08:47:35Z

Could we adjust the approach a bit?

I'm thinking that instead of using the version command line argument to build the docs in master into gh-pages in a folder specified by the argument, we should use the argument to checkout a git tag of the version and build it from there. That way no matter how many times for a given version and whichever branch you run it from, we will always know that it will always build what's versioned at that tag. With that we might be able to do better error checking to make sure we're not building docs for versions that don't exist (checking out a tag that doesn't exist should fail).

Maybe running the script without a version argument can checkout the latest from master then commit it to gh-pages in the HEAD folder. Then we'd be able to add a line to the .travis.yml file to just run the script and every time we build. Assuming all the build steps succeed, it should just commit the built docs at that commit to gh-pages.

Do you guys think that makes sense?

mbrookes · 2016-02-24T09:21:47Z

we should use the argument to checkout a git tag of the version and build it from there

Makes sense to me! 👌

Then we'd be able to add a line to the .travis.yml file to just run the script and every time we build. Assuming all the build steps succeed,

How does Travis distinguish between submitted PRs / pushes (for testing), and merged PRs (for building), or do we then consider building the docs site part of the testing?

it should just commit the built docs at that commit to gh-pages.

It does already, but how does that get from Travis' fork back to the callemall gh repo? That's why I added the -p argument - I assume it'll need to push (?), but only for merges, The Travis docs are super-unhelpful on this.

newoga · 2016-02-24T10:03:05Z

How does Travis distinguish between submitted PRs / pushes (for testing), and merged PRs (for building), or do we then consider building the docs site part of the testing?

Oh geez! I have fallen victim to nonsense thinking in the late hour 😪 I assumed we already were automating releases using Travis, on second look it seems like we're not. So yes that would be an issue.

Travis does support an npm deploy feature that can detect when versions change: https://docs.travis-ci.com/user/deployment/npm, we'd be able to hook into a deploy after script to do the necessary docs work. That being said, I'm looking at a lot of open source projects and I'm not seeing anyone that's using this feature so maybe we should skip it too.

It does already, but how does that get from Travis' fork back to the callemall gh repo? That's why I added the -p argument - I assume it'll need to push (?), but only for merges, The Travis docs are super-unhelpful on this.

Not completely sure. I figured Travis clones the repo from callemall/material-ui, not from a separate fork. So it's upstream should be here and it should be able to push directly.

There are a lot uncertainties with what I proposed. I'd say start with the change checking out from git tag first and maybe I'll be smarter after some sleep 😄

mbrookes · 2016-02-24T16:40:33Z

I figured Travis clones the repo from callemall/material-ui, not from a separate fork.

Mmm, yeah, I meant clone, not fork. And I don't know why I thought the remote wouldn't be set correctly - I have a local file:// clone of my normal clone of my fork of this repo (so I can have two branches checked out at the same time) so it gets confusing! I think we all need more sleep! 😴

I've updated to use tags for versions. I haven't tested as thoroughly as the previous version, but for four runs through (tagged version, HEAD, HEAD, later tagged version) it behaves as expected. Trying to build the same tagged version twice will fail, since the directory already exists in a commit, but that's no bad thing.

alitaheri · 2016-02-25T21:34:46Z

docs/gh-pages-build.js

+var execSync = require('child_process').execSync;
+
+var usage = '\nbuild <vn.n.n[-pre[.n]] | HEAD> [-p]\n';
+var versionsFile = './src/www/versions.json';


@mbrookes Always try resolving these relative paths using path.resolve(__dirname, './src/...') because relative paths are resolved relative to current working directory, so if someone does this: node docs/gh-pages-build.js from the root directory this won't work.

Well, much of the git wrangling assumes we're in docs, and it would get super messy and hard-to-read if we path.resolve all of those.

I was assuming this is going to be called in an automated fashion either for HEAD builds, or as part of @hai-cea's release process, or, if run manually, by using the npm start script.

No harm in making it fool proof, but much easier to process.chdir('__dirname'); though I think?

Well, much of the git wrangling assumes we're in docs, and it would get super messy and hard-to-read if we path.resolve all of those.

I see, well you're right, I didn't take those into account 😅

No harm in making it fool proof, but much easier to process.chdir('__dirname'); though I think?

That's actually a very smart move 👍 Yeah I think it's a lot safer 👍

mbrookes · 2016-02-26T16:53:56Z

If there's nothing further, lets squash, merge and get alpha.1 released.

We'll get an idea of and refinements needed after the first time it gets used for real.

alitaheri · 2016-02-26T17:01:25Z

I'm good 👍 👍

newoga · 2016-02-26T21:42:09Z

We'll get an idea of and refinements needed after the first time it gets used for real.

I'm good with that too!

[Docs] Add versions to docs site

alitaheri · 2016-02-26T22:47:47Z

Awesome 😍 I'll update, rebase and tidy up the release notes tomorrow 👍

mbrookes changed the title ~~[WIP] Add versions to docs site~~ [WIP][Docs] Add versions to docs site Feb 18, 2016

newoga reviewed Feb 19, 2016
View reviewed changes

mbrookes added docs Improvements or additions to the documentation PR: Needs Review labels Feb 19, 2016

oliviertassinari reviewed Feb 19, 2016
View reviewed changes

mbrookes added PR: needs revision The pull request can't be merged. More details is available on the code review or fails in the CI and removed PR: Needs Review labels Feb 20, 2016

mbrookes added PR: Needs Review and removed PR: needs revision The pull request can't be merged. More details is available on the code review or fails in the CI labels Feb 20, 2016

mbrookes mentioned this pull request Feb 23, 2016

[Docs] Add past versions to gh-pages branch #3434

Merged

mbrookes changed the title ~~[WIP][Docs] Add versions to docs site~~ [Docs] Add versions to docs site Feb 23, 2016

newoga reviewed Feb 24, 2016
View reviewed changes

alitaheri reviewed Feb 25, 2016
View reviewed changes

[Docs] Add gh-pages-build script, add versions DropDownMenu to LeftNav

2e2e5f0

mbrookes added this to the 0.15.0-alpha.1 Release milestone Feb 26, 2016

mbrookes added PR: Review Accepted and removed PR: Needs Review labels Feb 26, 2016

newoga added a commit that referenced this pull request Feb 26, 2016

Merge pull request #3383 from mbrookes/gh-pages-build

e9dd21c

[Docs] Add versions to docs site

newoga merged commit e9dd21c into mui:master Feb 26, 2016

mbrookes deleted the gh-pages-build branch January 20, 2018 22:35

		@@ -0,0 +1,83 @@
		import React from 'react';
		import ReactDOM from 'react-dom';

[Docs] Add versions to docs site #3383

[Docs] Add versions to docs site #3383

Conversation

mbrookes commented Feb 18, 2016

newoga commented Feb 18, 2016

mbrookes commented Feb 18, 2016

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

newoga commented Feb 19, 2016

mbrookes commented Feb 19, 2016

Choose a reason for hiding this comment

newoga commented Feb 19, 2016

mbrookes commented Feb 20, 2016

mbrookes commented Feb 23, 2016

oliviertassinari commented Feb 23, 2016

mbrookes commented Feb 23, 2016

oliviertassinari commented Feb 23, 2016

mbrookes commented Feb 24, 2016

newoga commented Feb 24, 2016

newoga commented Feb 24, 2016

mbrookes commented Feb 24, 2016

newoga commented Feb 24, 2016

mbrookes commented Feb 24, 2016

alitaheri commented Feb 24, 2016

Choose a reason for hiding this comment

newoga commented Feb 24, 2016

mbrookes commented Feb 24, 2016

newoga commented Feb 24, 2016

mbrookes commented Feb 24, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbrookes commented Feb 26, 2016

alitaheri commented Feb 26, 2016

newoga commented Feb 26, 2016

alitaheri commented Feb 26, 2016