Update documentation

othermachines, thank you for that patch!

I had to modify because I got these when I tried to apply it.

[asrob@umbrella bootstrap]$ git apply -v bootstrap-README-2466425.patch
bootstrap-README-2466425.patch:33: trailing whitespace.
a file hierarchy wizard and need to separate your theme into multiple files, 
bootstrap-README-2466425.patch:34: trailing whitespace.
insert additional `@import '...';` lines. 
Checking patch starterkits/less/less/README.txt...
Applied patch starterkits/less/less/README.txt cleanly.
warning: 2 lines add whitespace errors.

Therefore I attached a new patch.

Ah! Good catch :) One tiny nitpick though, I think instead of removing the example, we should offer a different one instead, like "tooltips.less" or something. Just to remain explicit and helpful.

And somehow we've gone from nitpick to questions about best practice... oh, woe...

Indeed. This has actually come up quite a few times in other issues. I think this issue is (or rather should be) more broad than just a single change here or there.

I'm attaching a couple related issues that will, ultimately, also affect the outcome of this file.

I am tempted we actually move this out of the repo and into a handbook page (similar to what http://cgit.drupalcode.org/bootstrap/commit/?id=a33544f7fd6a473d7e0456e3... accomplished).

That being said, one of the downsides (since that commit) that I have come to realize is that these handbook pages are "out of sync" or rather very specific to whichever codebase a person actually ends up with (i.e. 7.x-3.0 or 7.x-3.x-dev). Maybe we should move them back into the repo?

Ultimately, my goal has been to somehow move the documentation from the d.o handbook pages to something a little more specific. I have already bought http://drupal-bootstrap.org and perhaps, if we move the documentation back into the repo, we can somehow automatically parse it like api.drupal.org does using https://www.drupal.org/project/api.

Thoughts?

I like the approach of Drush: docs are in the markdown format in the repo (so they should alway correspond specific release), are built and hosted by https://readthedocs.org/ and accessible from http://drush.org.

Another issue should also be addressed: the domain name would suggest info about Bootstrap usage in Drupal in general. So I think, that there should be also some wiki, usable also by other project maintainers and users.

FYI and fair warning for the rest of this comment: I'm in the middle of moving so I'm a little overwhelmed. Also, I'm a little peeved at how this project's documentation is constantly hi-jacked/munged with every other little Drupal/Bootstrap related project out there. So please, do not take it personally... I'm just venting and hashing out my raw thoughts (don't have time for "amicable/politically-correct filtering" at the moment).

----

I originally though about readthedocs (like Drush uses) but have since moved away from that idea. Yes, while the main purpose of the site will be to provide general documentation (for this project), it is my goal to also provide advanced documentation/examples; examples which will need the Bootstrap base-theme.

Another issue should also be addressed: the domain name would suggest info about Bootstrap usage in Drupal in general. So I think, that there should be also some wiki, usable also by other project maintainers and users.

I actually decided on http://drupal-bootstrap.org specifically for this purpose:
https://www.drupal.org/project/bootstrap

We've had this namespace on d.o for years. It's only recently that other projects have started popping up, likely due to the success, popularity and opportunity this project has paved the way for.

As far as the "usable by other project maintainers and users" bit... that isn't going to happen; at least not initially anyway. Not to sound crass or insensitive, but I'm the one putting effort into all of this and do not see anyone else fronting the bill for the domain, server maintenance, site planning and development towards this idea/task.

Not to mention, there is no other Bootstrap related project that has this kind of usage... period. This project alone is the top #3 Drupal theme on d.o with over (at time of writing) 60k installs.

I'm sorry, but until some other Bootstrap related project has these kinds of numbers to justify a valid reason for hi-jacking/co-existing with this project, I don't see this site being used for anything else than this project.

x-ref: https://groups.drupal.org/node/466128#comment-1099793

I have said this once and I'll say it again: These handbook pages were originally created for https://www.drupal.org/project/bootstrap.

I realize that these handbook pages have become something a little more generic towards overall bootstrap/drupal concepts, but you have to look at where I originally placed https://www.drupal.org/documentation/theme/bootstrap. It is a child of Contributed themes, which is specifically for contributed [base-]theme projects on d.o.

Somehow, it has turned into a generic "free-for-all" dumping ground for any bootstrap related project and, quite honestly, I'm sick of it. I'm tired of having to constantly try and fight to keep it clean, concise and related to exactly what it was intended for in the first place.

So... I've relented in trying to fight that and instead opted for something that other people cannot touch: a separate site for documentation.

The real "goal" here (for this project) isn't to provide general support for other project maintainers (that may or may not work with this project), but rather to make some sort of "official" separation from the general documentation/concepts that the documentation in the handbook pages has become.

We can then find other parents/homes for the handbook sub-pages, like https://www.drupal.org/node/22803 or https://www.drupal.org/node/45471 maybe.

FWIW, I'll throw our name in to help with site planning should drupal-bootstrap.org come to pass. If it's going to work the execution will be key and I have a pretty extensive background in IA/UX.

@othermachines, I would be very interested in talking with you :) Maybe sometime next week (this week[end] is a little crazy for me ATM). I could not agree more with this statement!

I'm a big fan of README/markdown files

I generally am as well. The only reason they were moved out was because prior to and during #1840980: [meta] Bootstrap 3.0, the codebase was constantly changing it was simply easier to just point people to one place for this (as the sub-theming process remained, relatively, unchanged). It was also rather new in the Drupal handbook scope, so no other project had anything else out there regarding Bootstrap specifics really.

Not a big fan of visiting a separate website for documentation

Neither am I (for Drupal projects anyway). However, I see no great way to solve this problem otherwise. The main selling point that even I keep telling myself is that it would have a Bootstrap base-theme behind it and allow for easier (and possibly interactive) examples to be shown. There is only so much we can do with the handbook pages and/or simple markdown text.

I'm not opposed to the idea if it's well implemented...

I agree. I do not like doing subpar work. It's ineffective and often confusing to do so. If anything I would like to modal it similar to the existing Bootstrap documentation, kind of how I have done with the new Bootstrap Anchor plugin I have been developing. I really don't want to copy their site style exactly per se, but the layout and general concept is rather decent IMO.

I confess that I am unclear on how Drush plays into this question.

He was simply stating that Drush auto generates their doc pages from their codebase using Read the Docs service: https://readthedocs.org/projects/drush/. I had originally thought of this as well, but quickly rejected it because if we're going to go this route, we may as well make it Bootstrap based and allow for more interactive and dynamic documentation/examples.

we can somehow automatically parse it like api.drupal.org does using https://www.drupal.org/project/api.

I'm not entirely 100% sure this is how we'll do it TBH, it's just one idea. After spending some time with Jekyll and developing Bootstrap Anchor's documentation (almost identical in how the main Bootstrap project does it), I've come to respect the simplicity of it without needing a CMS behind it.

That being said, I would find it rather ironic and almost insulting if we didn't use this base-theme for our own docs... just sayin :) I think a hybrid solution of some kind will be good enough, perhaps utilizing things like the API module, https://www.drupal.org/project/markdown and https://www.drupal.org/project/pygmentizer.

So, the more I think about it, I think it does make more sense to move the docs back into the repo. Despite whatever tool we actually end up using to scrape it, I suspect that will still only be about 25% of what I envision that site to become.

I would love to see full fledged examples and even advanced examples or "how-to's". Perhaps have a vetting process that allows people to register to help maintain the documentation other than just the "maintainers". I see it becoming more of the hub for the Drupal <-> Bootstrap eco-system and yes, eventually perhaps letting other projects and maintainers weigh in or have their own sections.

I'm really not trying to be the "bad guy", limit or stifle other projects/ideas... but I have to put my foot down and start somewhere just to corral this project's docs and make them more coherent/decisive.

Whatever direction we decide to go with external community involvement, it will seriously need to be planned out. I will not risk letting other projects hi-jack the site and abuse it for self-promotion.

Assigning to @burnsjeremy, who is our new documentation co-maintainer.

Here's a quick update for our new documentation site: http://drupal-bootstrap.org

• Created the d.o hosted GitClone module to handle the branch repository syncs for the API module.
• Created the local/custom db_site module to manage these repositories (and other site wide generic alterations).
• Created the local/custom db_markdown custom module to handle our markdown parsing.
• Created the local/custom db_api module to integrate db_markdown with the API module.
• Created the local/custom bootstrap_subtheme which houses a lot of front end customizations.
• Replaced core API's "language syntax coloring" (which is limited to PHP only) with PrismJS. Note: this actually includes automatic highlighting of source code lines via the PrismJS line-highlight plugin. The syntax is: #code.[pattern], e.g. #code.33-50 would be lines 33 - 50.

The site is, mostly, fully up and running. It is, now, just a matter of updating all the documentation in the repo so it can be properly parsed by the site.

@todos:

• Migrate some of the handbook pages into code.
• Create and organize topics
• Create a @mainpage to list these topics
• Go through all existing coded documentation, cleanup and standardize

---

On a semi-related side note: We actually had our first real use case for this site. It really easy way to link to specific code on our new documentation site!
https://www.drupal.org/node/2560097#comment-10274167

My goal is to release 7.x-3.1 Monday morning once this issue is finalized. If you'd like to help out, please join #drupal-bootstrap in freenode IRC so we can converse in real time and also work from the docs branch.

I would like this to be reviewed by the community: http://drupal-bootstrap.org.

I will still make the release Monday if no issues/comments are made regarding this though.

This looks really solid. Just found a couple of tidbits, see the commit.

http://drupal-bootstrap.org/ is not working.

It's back up.

Also, please don't re-open old issues.