Commit 03cf73c9 authored by markcarver's avatar markcarver

Issue #2466425: Update documentation

parent a4c3210a
<!-- @mainpage -->
<!-- @summary Documentation landing page and topics for the http://drupal-bootstrap.org site. -->
# Drupal Bootstrap Documentation
{.lead} The official documentation site for the [Drupal Bootstrap] base theme
The majority of this site is automatically generated from source files
located through out the project's repository. Topics are extracted from Markdown
files and the rest is extracted from embedded PHP comments.
---
## Topics
Below are some topics to help get you started using the [Drupal Bootstrap] base
theme. They are ordered solely on quickest implementation and ease of use. The
base theme can cover many different use cases. You may find one or more of these
topics useful. They range from a quick CDN based implementation (with minimal
coding effort) to full on sub-theme architecture complete with template and
preprocess overrides.
#### @link settings Theme Settings @endlink
#### @link subtheme Sub-Theming @endlink
- @link subtheme_drush Drush Support @endlink
- @link subtheme_utility Utility Functions @endlink
#### @link api APIs @endlink
#### @link registry Theme Registry @endlink
#### @link project Project Development @endlink
- @link project_grunt Grunt Tasks @endlink
- @link project_releases Releases @endlink
---
## Terminology
The term **"bootstrap"** can be used excessively through out this project's
documentation. For clarity, we will attempt to use it verbosely in one of the
following ways:
- **[Drupal Bootstrap]** refers to the Drupal base theme project.
- **[Bootstrap Framework](http://getbootstrap.com)** refers to the external
front end framework.
- **[drupal_bootstrap](https://api.drupal.org/apis/drupal_bootstrap)** refers
to Drupal's bootstrapping process or phase.
When referring to files inside the [Drupal Bootstrap] project directory, they
will always start with `./` and continue to specify the full path to the file
or directory inside it. For example, the file that is responsible for displaying
this text is located at `./README.md`.
When referring to files inside a sub-theme, they will always start with
`./example_subtheme/` and continue to specify the full path to the file or
directory inside it. For example, the main file Drupal will search for:
`./example_subtheme/template.php`.
[Drupal Bootstrap]: https://www.drupal.org/project/bootstrap
<!-- @file Project Page -->
# Bootstrap
> Sleek, intuitive, and powerful mobile first front-end framework for faster and
> easier web development. Bootstrap has become one of the most popular front-end
> frameworks and open source projects in the world.
This base theme bridges the gap between Drupal and the [Bootstrap Framework].
### Features
- [jsDelivr CDN](http://www.jsdelivr.com) for "out-of-the-box" styling and
faster page load times.
- [Bootswatch](http://bootswatch.com) theme support, if using the CDN.
- Glyphicons support via [Icon API](https://www.drupal.org/project/icon).
- Extensive integration and template/preprocessor overrides for most of the
[Bootstrap Framework] CSS, Components and JavaScript
- Theme settings to further enhance the Drupal Bootstrap integration:
- [Breadcrumbs](http://getbootstrap.com/components/#breadcrumbs)
- [Navbar](http://getbootstrap.com/components/#navbar)
- [Popovers](http://getbootstrap.com/javascript/#popovers)
- [Tooltips](http://getbootstrap.com/javascript/#tooltips)
- [Wells](http://getbootstrap.com/components/#wells) (per region)
### Documentation
See our dedicated [documentation site](http://drupal-bootstrap.org).
[Bootstrap Framework]: http://getbootstrap.com
<!-- @file Frequently Asked Questions -->
<!-- @defgroup -->
# FAQ - Frequently Asked Questions
## Internet Explorer Compatibility
The [Bootstrap Framework] does not officially support older Internet Explorer
[compatibility modes]. To ensure you are using the latest rendering mode for IE,
consider installing the [HTML5 Tools](https://drupal.org/project/html5_tools)
module.
Internet Explorer 8 requires the use of [Respond.js] to enable media queries
(Responsive Web Design). However, [Respond.js] does not work with CSS that is
referenced via a CSS `@import` statement, which is the default way Drupal
adds CSS files to a page when CSS aggregation is disabled. To ensure
[Respond.js] works properly, enable CSS aggregation at the bottom of:
`admin/config/development/performance`.
[Bootstrap Framework]: http://getbootstrap.com
[Respond.js]: https://github.com/scottjehl/Respond
[compatibility modes]: http://getbootstrap.com/getting-started/#support-ie-compatibility-modes
<!-- @file The "Getting Started" topic. -->
<!-- @defgroup -->
# Getting Started
## Requirements
All [Bootstrap Framework] JavaScript plugins require jQuery 1.9.0+. The
preferred method for updating Drupal's jQuery is to install the
[jQuery Update](https://drupal.org/project/jquery_update).
## Installation
- Install the Bootstrap base theme in `sites/all/themes` or a similar
`sites/*/themes` folder.
- Ensure that jQuery has been configured to meet the [Bootstrap Framework]
minimum version requirement.
## Understanding the Fundamentals
Generally speaking, you should really read the entire [Bootstrap Framework]
documentation site, if you haven't already. Here are the four basic "sections"
the site is split into:
- [Getting Started](http://getbootstrap.com/getting-started) - An overview of
the [Bootstrap Framework], how to download and use, basic templates and
examples, and more.
- [CSS](http://getbootstrap.com/css/) - Global CSS settings, fundamental HTML
elements styled and enhanced with extensible classes, and an advanced grid
system.
- [Components](http://getbootstrap.com/components/) - Over a dozen reusable
components built to provide iconography, dropdowns, input groups, navigation,
alerts, and much more.
- [JavaScript](http://getbootstrap.com/javascript/) - Bring the
[Bootstrap Framework] components to life with over a dozen custom jQuery
plugins. Easily include them all, or one by one.
[Bootstrap Framework]: http://getbootstrap.com
<!-- @file Documentation landing page and topics for the http://drupal-bootstrap.org site. -->
<!-- @mainpage -->
# Drupal Bootstrap Documentation
{.lead} The official documentation site for the [Drupal Bootstrap] base theme
The majority of this site is automatically generated from source files
located through out the project's repository. Topics are extracted from Markdown
files and the rest is extracted from embedded PHP comments.
---
## Topics
Below are some topics to help get you started using the [Drupal Bootstrap] base
theme. They are ordered solely on quickest implementation and ease of use.
#### @link getting_started Getting Started @endlink
#### @link faq FAQ @endlink
#### @link settings Theme Settings @endlink
#### @link subtheme Sub-Theming @endlink
- @link subtheme_drush Drush Support @endlink
- @link subtheme_utility Utility Functions @endlink
#### @link api APIs @endlink
#### @link registry Theme Registry @endlink
#### @link project Project Development @endlink
- @link project_grunt Grunt Tasks @endlink
- @link project_releases Releases @endlink
---
## Terminology
The term **"bootstrap"** can be used excessively through out this project's
documentation. For clarity, we will attempt to use it verbosely in one of the
following ways:
- **[Drupal Bootstrap]** refers to the Drupal base theme project.
- **[Bootstrap Framework](http://getbootstrap.com)** refers to the external
front end framework.
- **[drupal_bootstrap](https://api.drupal.org/apis/drupal_bootstrap)** refers
to Drupal's bootstrapping process or phase.
When referring to files inside the [Drupal Bootstrap] project directory, they
will always start with `./` and continue to specify the full path to the file
or directory inside it. For example, the file that is responsible for displaying
this text is located at `./README.md`.
When referring to files inside a sub-theme, they will always start with
`./example_subtheme/` and continue to specify the full path to the file or
directory inside it. For example, the main file Drupal will search for:
`./example_subtheme/template.php`.
[Drupal Bootstrap]: https://www.drupal.org/project/bootstrap
<!-- @file Overview of the APIs provided by Drupal Bootstrap. -->
<!-- @defgroup -->
<!-- @summary Overview of the APIs provided by Drupal Bootstrap. -->
# APIs
{.alert.alert-warning} Needs documentation.
<!-- @file Overview for maintaining and developing the Drupal Bootstrap project. -->
<!-- @defgroup -->
<!-- @summary Overview for maintaining and developing the Drupal Bootstrap project. -->
# Project Development
Generally speaking, these topics will not be very helpful to you unless you are
......
<!-- @file Lists the grunt tasks commonly used in project development. -->
<!-- @defgroup -->
<!-- @ingroup -->
<!-- @summary Lists the grunt tasks commonly used in project development. -->
# Grunt Tasks
There are several tasks available to run, please execute `grunt --help` to view
......
<!-- @file Provides detailed instructions for creating a release for the project. -->
<!-- @defgroup -->
<!-- @ingroup -->
<!-- @summary Provides detailed instructions for creating a release for the project. -->
# Releases
This project attempts to provide more structured release notes. This allows the project to communicate more effectively
......
<!-- @file Overview of the theme registry in Drupal Bootstrap. -->
<!-- @defgroup -->
<!-- @summary Overview of the theme registry in Drupal Bootstrap. -->
# Theme Registry
{.alert.alert-warning} Needs documentation.
<!-- @file Overview of the theme settings provided by Drupal Bootstrap. -->
<!-- @defgroup -->
<!-- @summary Overview of the theme settings provided by Drupal Bootstrap. -->
# Theme Settings
{.alert.alert-warning} Needs documentation.
<!-- @file Overview of how to sub-theme the Drupal Bootstrap base theme. -->
<!-- @defgroup -->
<!-- @summary Overview of sub-theming from Drupal Bootstrap. -->
# Sub-Theming
{.alert.alert-warning} Needs documentation.
Below are instructions on how to create a Bootstrap sub-theme. There are several
different variations on how to accomplish this task, but this topic will focus
on the two primarily and most common ways:
1. Using the "out-of-the-box" implementation via the [jsDelivr CDN].
2. Using the [Bootstrap Framework] source and a local [LESS] preprocessor.
- [Prerequisite](#prerequisite)
- [Setup](#setup)
- [Enable](#enable)
- [File Structure](#file_structure)
- [Icons](#icons)
## Prerequisite
Read the @link getting_started Getting Started @endlink documentation topic.
### Conditional Requirements for Method 1: Bootstrap Source Files
- When using 7.x-3.0: [Bootstrap 3.x.x Source](https://github.com/twbs/bootstrap/releases)
- The Bootstrap source files are written with LESS language. You must use a **[local](https://www.google.com/search?q=less+compiler)** LESS compiler.
## Unsupported Modules
The following modules are not "officially" supported or documented by the
Drupal Bootstrap base theme. This does not mean we "dislike" them or have any
"ill will" towards them. It is more about the time, energy and effort it would
take to document "every possible scenario".
It is certainly possible that some of these modules may eventually come off this
list. That is, only if enough people actually help to contribute solid solutions
towards a common goal.
Until then, however, if you choose to use one of these modules you really do so
at your own expense. Do not expect support from this base theme or the project
you are attempting to integrate with. You are sailing into the unknown:
- Color module (in core)
- [Bootstrap API](https://www.drupal.org/project/bootstrap_api)
- [Bootstrap Library](https://www.drupal.org/project/bootstrap_library)
- [Display Suite](https://www.drupal.org/project/ds)
- [Display Suite Bootstrap Layouts](https://www.drupal.org/project/ds_bootstrap_layouts)
- [LESS module](https://drupal.org/project/less)
- [Panels](https://www.drupal.org/project/panels)
- [Panels Bootstrap Layouts](https://www.drupal.org/project/panels_bootstrap_layouts)
## Setup
Copy the starter kit sub-theme into `sites/all/themes` or a respective
`sites/*/themes` folder. You should never modify a theme or a sub-theme bundled
directly as all changes would be lost if the base theme were to be updated.
Once copied, rename the folder to something of your choosing:
`my_bootstrap_theme`. Then make sure you rename the
`bootstrap_subtheme.info.starterkit` file to match the folder name, like:
`my_bootstrap_theme.info`. Be sure to change the name and description properties
inside the file as well.
{.alert.alert-info} **IMPORTANT NOTE:** Ensure that the `.starterkit` suffix is
not added to your sub-theme's .info filename. This suffix is simply a stop-gap
measure to ensure that the bundled starter kit sub-theme cannot be enabled or
used directly. This helps people unfamiliar with Drupal avoid modifying the
starter kit sub-theme directly and forces the new sub-theme to be properly
configured.
### Bootstrap Methods
There are currently two types of supported methods for adding Bootstrap into
your sub-theme. By default, the Bootstrap base theme enables a CDN to provide
the necessary files. If this method suits you then you can skip this step.
The first method is probably the most dynamic and will grant you the ability to
change the variables and utilize the mixins provided by Bootstrap.
The second method is rather simple and utilizes CDN Bootstrap via the base
theme. It is very static and will require you to override existing styling in
your sub-theme.
Regardless of which method you choose, you will need to un-comment the
appropriate lines for your desired method in your sub-theme's .info file.
#### Method 1: Bootstrap Source Files
Download and extract the [Latest Bootstrap source](https://github.com/twbs/bootstrap/releases)
into your new sub-theme. After it has been extracted, the folder should read
`bootstrap`. If for whatever reason you have an additional bootstrap folder
wrapping the the bootstrap folder (like: bootstrap/bootstrap), remove the
wrapping bootstrap folder. You will not need to touch these files again.
This allows the framework to be updated in the future.
Copy over the bootstrap/less/variables.less to less/variables.less then fix
paths as stated in less/README.txt.
Compile the `./less/style.less` file. A new file should be generated as
`./css/style.css`.
Now, you will need to uncomment the lines under 'METHOD 1: Bootstrap Source' in
your sub-theme's .info file (pertaining to this method).
#### Method 2: [jsDelivr CDN]
This method is rather simple and the easiest. You don't have to do anything
unless you wish to override the default Bootstrap base theme settings. If so,
just un-comment the lines pertaining to Method 2.
Edit the provided `./css/style.css` file to your liking.
## Enable
Navigate to `admin/appearance` and click "Enable and set default" for your
newly created sub-theme.
## File Structure
The following paths are relative to your sub-theme's base folder. These folders
have an initial README.md files. Please read them for a more detailed
explanation of their contents.
- `./css` - Compiled sub-theme source files.
- `./less` - Sub-theme source files.
- `./templates` - Template files.
## Icons
Bootstrap comes packaged with the default [Glyphicons](http://getbootstrap.com/components/#glyphicons).
This base-theme has support for utilizing these icons via the [Icon API](https://drupal.org/project/icon).
However, given the limited capability of static sprite images, it is
recommended that you consider using an alternative solution, like
[Fontello](http://drupal.org/project/fontello) instead.
[Bootstrap Framework]: http://getbootstrap.com
[jsDelivr CDN]: http://www.jsdelivr.com
[LESS]: http://lesscss.org
<!-- @file Lists available Drush commands and explains what they do. -->
<!-- @defgroup -->
<!-- @ingroup -->
<!-- @summary Lists available Drush commands and explains what they do. -->
# Drush Support
{.alert.alert-warning} Needs documentation.
<!-- @file Lists available utility functions available to use in Drupal Bootstrap sub-themes. -->
<!-- @defgroup -->
<!-- @ingroup -->
<!-- @summary Lists available utility functions available to use in Drupal Bootstrap sub-themes. -->
# Utility Functions
{.alert.alert-warning} Needs documentation.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment