Bring back the `/docs` directory #12037

mdo · 2013-12-29T07:11:52Z

This moves all documentation files to a /docs subdirectory to help clean up the file tree. Here are some thoughts on what's changed and why it matters.

All .html files, /examples, and Jekyll directories have been moved to a subfolder, /docs.
By far the biggest win is organization. It cleans up the file tree for beginners who have no idea what some of this stuff is and makes it easier for us as maintainers (@twbs/team) to stare at this stuff all day.
By far the biggest downside is that this duplicates some code. However, I've tried to keep that to a minimum by only bringing over the minified CSS and JS files. All the fonts are duped though.
As part of this, the _config.yml file has been cleaned up. Nested configs look way better. I was also able to remove all the exclude lists since the stuff we really need to compile the docs is now all in one spot, free of extra noise.
I've also replaced all instances of {{ page.base_url }} with {{ site.baseurl }}. Better to use an official config setting than a custom one on each page. This does, however, mean that folks who fork Bootstrap need to change the baseurl option in Jekyll if they wish to host our docs themselves. I'm not worried in the slightest about this.

By moving the Jekyll folders, our examples, docs assets, HTML files, and docs license to the subdirectory, we effectively lose 13 items from the root directory. The root file tree looks like this now:

├─ dist/
├─ docs/
├─ fonts/
├─ js/
├─ less/
├─ test-infra/
├─ .csscomb.json
├─ .csslintrc
├─ .editorconfig
├─ .gitattributes
├─ .gitignore
├─ .travis.yml
├─ CNAME
├─ CONTRIBUTING.md
├─ Gruntfile.js
├─ LICENSE
├─ README.md
├─ _config.yml
├─ bower.json
├─ composer.json
└─ package.json

It's a bit better, but could still use some cleanup. I'm curious if we could punt any of those other files somewhere else. It'd be great if a repo could just have a .files/ directory for this stuff.

/cc @fat, because <3.

…t/, only take minified ones

mdo · 2013-12-29T07:13:07Z

Unrelated, but why are all our builds failing? @fat, Travis says the qunit tests are fubared—perhaps something you did in the last week?

cvrebert · 2013-12-29T08:31:21Z

@mdo There's some recent mild wonkiness in the Sauce service or toolchain with a couple of the browser/OS combos; don't think it's an actual problem in our JS. (Might be a bad version update on their end or something.)

mdo · 2013-12-29T08:38:55Z

@cvrebert Gah, okay. Anything we can do? Even if it's just to connect with them? And let me know your thoughts on this PR, too, please :).

cvrebert · 2013-12-29T08:39:03Z

(Although the fact that our QUnit version is so outdated can't be helping things; see #11240).

cvrebert · 2013-12-30T04:43:54Z

@mdo @fat: I stand corrected. We are getting some real JS errors; the grunt plugin is just not reporting this fact very well (again, possibly due to old QUnit).

Windows 8.1 Firefox: 2 failed tests: http://saucelabs.com/tests/f03379649e1a495f87742752b6f6998e
Linux Chrome: 1 failed test: http://saucelabs.com/tests/dcd00a7cc57247f5821253de102c27a7

(And for that matter, OS X Firefox has been failing 1 tooltip test for a while, which is why it's been disabled in our Sauce config, along with all IE versions... 😞 Would be nice if we could get all the platforms enabled+passing again.)

cvrebert · 2013-12-30T04:51:20Z

Gruntfile.js

@@ -196,6 +196,23 @@ module.exports = function (grunt) {
        expand: true,
        src: ['fonts/*'],
        dest: 'dist/'
+      },
+      dist_css: {


Should be in mixedCase per JS convention? Or is there a Grunt convention for task naming?

Also, perhaps include "doc" or "docs" in the names of these new tasks?

cvrebert · 2013-12-30T05:01:48Z

I think it's definitely a net win to do this move.

mdo · 2013-12-31T18:53:48Z

I stand corrected. We are getting some real JS errors; the grunt plugin is just not reporting this fact very well (again, possibly due to old QUnit).

@cvrebert Let's open a new issue and ping @fat about that stuff. In the mean time, perhaps we comment those out again to get some green back in our lives?

nschonni · 2013-12-31T19:18:28Z

Gruntfile.js

@@ -199,6 +199,23 @@ module.exports = function (grunt) {
        expand: true,
        src: ['fonts/*'],
        dest: 'dist/'
+      },
+      docsDistCss: {


This can replace all three targets

docs: { expand: true, cwd: './dist', src: [ '{css,js}/*.min.*', '{css,js}/*.map', 'fonts/*' ], dest: 'docs/dist' }

nschonni · 2013-12-31T19:41:25Z

Gruntfile.js

+        cwd: './dist',
+        src: [
+          '{css,js}/*.min.*',
+          '{css}*.map',


Sorry, this is my bad from the original snippet. There should be a / after {css}

Nah, it was my fault I think—I changed the line to not include ,js within the braces (unless you edited the comment). Either way, all set :).

😉 I did edit it a second or two after I posted

Bring back the `/docs` directory

Refs #12083 & #12037

mdo added 3 commits December 28, 2013 22:47

Rearrange repository contents because muahahahahahaha

a9c829b

Streamline copy process by not bringing over full files into docs/dis…

f10cf21

…t/, only take minified ones

no more page.base_url

70b8b33

cvrebert reviewed Dec 30, 2013
View reviewed changes

cvrebert mentioned this pull request Dec 30, 2013

Autogenerate the customizer's variables form #11158

Merged

mdo added 2 commits December 31, 2013 10:38

Merge branch 'master' into docs_dir

0df96d8

@cvrebert's feedback

1e4540f

nschonni reviewed Dec 31, 2013
View reviewed changes

@nschonni's feedback <3

b43371c

nschonni reviewed Dec 31, 2013
View reviewed changes

mdo added 3 commits December 31, 2013 11:57

typo

78e1af5

Fixes #12046: move .csscomb.json and .csslintrc to less/ folder

ac3f48b

Merge branch 'master' into docs_dir

05cc208

mdo added a commit that referenced this pull request Dec 31, 2013

Merge pull request #12037 from twbs/docs_dir

8812856

Bring back the `/docs` directory

mdo merged commit 8812856 into master Dec 31, 2013

mdo deleted the docs_dir branch December 31, 2013 21:43

mdo mentioned this pull request Dec 31, 2013

v3.1.0 ship list #11734

Closed

cvrebert added a commit that referenced this pull request Jan 4, 2014

Replace lingering page.url instance with site.baseurl

84c33a8

Refs #12083 & #12037

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bring back the `/docs` directory #12037

Bring back the `/docs` directory #12037

mdo commented Dec 29, 2013

mdo commented Dec 29, 2013

cvrebert commented Dec 29, 2013

mdo commented Dec 29, 2013

cvrebert commented Dec 29, 2013

cvrebert commented Dec 30, 2013

cvrebert Dec 30, 2013

cvrebert Dec 30, 2013

mdo Dec 31, 2013

cvrebert commented Dec 30, 2013

mdo commented Dec 31, 2013

nschonni Dec 31, 2013

nschonni Dec 31, 2013

mdo Dec 31, 2013

nschonni Dec 31, 2013

Bring back the /docs directory #12037

Bring back the /docs directory #12037

Conversation

mdo commented Dec 29, 2013

mdo commented Dec 29, 2013

cvrebert commented Dec 29, 2013

mdo commented Dec 29, 2013

cvrebert commented Dec 29, 2013

cvrebert commented Dec 30, 2013

cvrebert Dec 30, 2013

Choose a reason for hiding this comment

cvrebert Dec 30, 2013

Choose a reason for hiding this comment

mdo Dec 31, 2013

Choose a reason for hiding this comment

cvrebert commented Dec 30, 2013

mdo commented Dec 31, 2013

nschonni Dec 31, 2013

Choose a reason for hiding this comment

nschonni Dec 31, 2013

Choose a reason for hiding this comment

mdo Dec 31, 2013

Choose a reason for hiding this comment

nschonni Dec 31, 2013

Choose a reason for hiding this comment

Bring back the `/docs` directory #12037

Bring back the `/docs` directory #12037