Very minor nitpick. This should be removed:


```
./less/bootstrap.less
./less/responsive.less
./less/variables.less
```

and this:


And finally, the `./less/style.less` file is the glue that holds it all
together and compiles everything into one file. Generally, you will not need
to modify this file unless you need to add or remove imported files. For
example, if you do not want your site to have responsive capabilities, free to
comment or remove that line.
If you are a file hierarchy wizard and need to
separate your theme into multiple files, insert additional `@import '...';`
lines.

Patch to follow.

Members fund testing for the Drupal project. Drupal Association Learn more

Comments

othermachines’s picture

Status: Active » Needs review
FileSize
1.5 KB
asrob’s picture

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.

othermachines’s picture

Awww, really? That seems to only happen when I'm using Windows. (Sure, always blame Windows. :P)

Thanks for re-rolling.

markcarver’s picture

Status: Needs review » Needs work

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.

othermachines’s picture

I believe a nitpick on a nitpick is a nitpickpick. :)

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.

I would agree with that except tooltips.less is not duplicated in the starterkit's less/ folder. We're left with bootstrap.less and variables.less, neither of which are optional of course.

I suppose for the sake of example we could point out that @import 'header'; (or footer) could be commented out or removed from style.less, but this is probably just overcomplicating things since there's no overhead saved by doing so.

That being said, this can still be improved.

  1. 'fixes.less' is now 'overrides.less'.


  2. Here's a grammatical tweak:

    The following files are simply duplicates from the Bootstrap library. With
    modifications in were
    which have been modified to reference the imports.

  3. There was one thing that tripped me up after I updated the Bootstrap framework which may be worth mentioning in this particular README. In addition to updating the @import paths in bootstrap.less I also had to modify @icon-font-path: "../fonts/"; in variables.less.

Putting it all together!

The following files are simply duplicates from the Bootstrap library which have
been modified to reference the imports: 
```
./less/bootstrap.less
./less/variables.less
```

In theory, you could replace them if you update the Bootstrap framework by
copying them from that framework again. Just make sure to modify the paths
to reference the `./bootstrap` folder. For example:

In bootstrap.less (modify paths for all except variables.less):
```
@import "variables.less";
@import "../bootstrap/less/mixins.less";
```
In variables.less:
```
@icon-font-path: "../bootstrap/fonts/";
```

The `./less/variables.less` file is generally where you will spend most of
your time customizing the various Bootstrap settings. Feel free to manually
edit it or even replace it with a service like
[BootTheme](http://www.boottheme.com).

The `./less/overrides.less` file contains various Bootstrap and Drupal fixes. 
It may contain a few enhancements, feel free to edit this file as you see fit.

The following files are relatively blank (they may contain some code for the
inital sub-theme), but this is where you will actually spend most of your time
specifying specific styling for your sites configuration.
```
./less/header.less
./less/content.less
./less/footer.less
```

And finally, the `./less/style.less` file is the glue that holds it all
together and compiles everything into one file. Generally, you will not need
to modify this file unless you need to add or remove imported files. If you are
a file hierarchy wizard and need to separate your theme into multiple files, 
insert additional `@import '...';` lines. 

othermachines’s picture

One more thing:

Is it a good idea to say that variables.less can (theoretically) be copied over after an update, and then go on to suggest that this is where customizations should live?

I don't modify this file as a rule (beyond changing the paths), but create a separate file for customizations.

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

markcarver’s picture

Title: Remove references to deprecated responsive.less in starterkit documentation » Update documentation
Priority: Minor » Major
Related issues: +#2250349: Add new variables to variables.less, +#2261189: Add Drush support for creating sub-themes

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?

milos.kroulik’s picture

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.

markcarver’s picture

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.

othermachines’s picture

I'm a big fan of README/markdown files - I guess because my happy place is with my text editor. I also like that they can be revisioned in tandem with the project. Of course since nobody loves writing documentation as much as code it often falls behind. But it's something to strive for.

Not a big fan of visiting a separate website for documentation, but that could just be trauma leftover from an Ubercart project (I still twitch when I think about it). I'm not opposed to the idea if it's well implemented, especially after learning about what happened to the Bootstrap docs here on d.o. (I poked my head in when I was updating the framework on my subthemes but quickly turned to the README when I couldn't find anything there.)

I confess that I am unclear on how Drush plays into this question. But I will say that I use it and rely on it and any proposal that means more Drush will most certainly get a big thumbs up from me!

@markcarver - 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’s picture

...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.

I somehow missed this on first read. Really like the idea.

markcarver’s picture

Priority: Major » Critical

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.

markcarver’s picture

Assigned: Unassigned » burnsjeremy

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

markcarver’s picture

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

  • markcarver committed 6147988 on 8.x-3.x
    Issue #2466425: Update documentation
    
    Conflicts:
    README.txt
    

  • wundo committed 45531c1 on 7.x-3.x
    Issue #2466425: Updates Gruntfile.js to reflect changes in the...

  • wundo committed 80d62ed on 7.x-3.x
    Issue #2466425: Changing from README.md to grunt.md
    

  • markcarver committed 35da74d on 8.x-3.x authored by wundo
    Issue #2466425: Changing from README.md to grunt.md
    
  • markcarver committed 79d2210 on 8.x-3.x authored by wundo
    Issue #2466425: Updates Gruntfile.js to reflect changes in the...
markcarver’s picture

Assigned: burnsjeremy » markcarver

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.

markcarver’s picture

Assigned: markcarver » Unassigned
Status: Needs work » Needs review

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.

  • neardark committed e5b707c on 7.x-3.x
    Issue #2466425 by neardark: Fixed tidbits in documentation
    
neardark’s picture

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

  • neardark committed d56dfad on 8.x-3.x
    Issue #2466425 by neardark: Fix tidbits in documentation
    
markcarver’s picture

Status: Needs review » Fixed

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

Sinan Erdem’s picture

Status: Closed (fixed) » Needs work
markcarver’s picture

Status: Needs work » Closed (fixed)

It's back up.

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