Documentation showing on bit-docs-website

Author: leoj3n

bit-docs.js

@@ -9,11 +9,10 @@ var mergeOnto = function(prop, dest, source){
 };
 
 /**
+ * @parent plugins
  * @module {function} bit-docs-generate-html
+ * @group bit-docs-generate-html/theme theme
  * @group bit-docs-generate-html/modules modules
- * @group bit-docs-generate-html/styles styles
- * @group bit-docs-generate-html/templates templates
- * @parent plugins
  *
  * @description Generates HTML for a docMap.  Supports plugins.
  *

site/default/static/styles/mixins.less

@@ -1,7 +1,7 @@
 /**
- * @parent bit-docs-generate-html/styles
- * @page bit-docs-generate-html/styles/mixins mixins
- * @group bit-docs-generate-html/styles/mixins/helper #helper
+ * @parent bit-docs-generate-html/theme/styles
+ * @page bit-docs-generate-html/theme/styles/mixins mixins
+ * @group bit-docs-generate-html/theme/styles/mixins/helper #helper
  *
  * @description Mixins for site-wide visual layout.
  *
@@ -12,8 +12,8 @@
 
 #helper {
   /**
-   * @function bit-docs-generate-html/styles/mixins/helper/padding .padding
-   * @parent bit-docs-generate-html/styles/mixins/helper
+   * @function bit-docs-generate-html/theme/styles/mixins/helper/padding .padding
+   * @parent bit-docs-generate-html/theme/styles/mixins/helper
    *
    * Sets padding for passed sides.
    *
@@ -22,7 +22,7 @@
    * @param {String} @sides A space-separated list of "sides", like `left right`.
    *
    * @param {Number} @amount An amount of padding in pixels, defaults to
-   * [bit-docs-generate-html/styles/variables/@defaultPadding @defaultPadding].
+   * [bit-docs-generate-html/theme/styles/variables/@defaultPadding @defaultPadding].
    * 
    * @body
    *
@@ -39,8 +39,8 @@
   }
 
   /**
-   * @function bit-docs-generate-html/styles/mixins/helper/flex .flex
-   * @parent bit-docs-generate-html/styles/mixins/helper
+   * @function bit-docs-generate-html/theme/styles/mixins/helper/flex .flex
+   * @parent bit-docs-generate-html/theme/styles/mixins/helper
    *
    * Sets flexbox "grow" and "shrink" in most compatible way.
    *
@@ -69,8 +69,8 @@
   }
 
   /**
-   * @function bit-docs-generate-html/styles/mixins/helper/property-names .property-names
-   * @parent bit-docs-generate-html/styles/mixins/helper
+   * @function bit-docs-generate-html/theme/styles/mixins/helper/property-names .property-names
+   * @parent bit-docs-generate-html/theme/styles/mixins/helper
    * @hide
    *
    * Helper for setting multiple dash properties to same value.
@@ -109,8 +109,8 @@
 // Flexbox (flexbugs: https://github.com/philipwalton/flexbugs)
 
 /**
- * @property .display-flex
- * @parent bit-docs-generate-html/styles/mixins
+ * @property bit-docs-generate-html/theme/styles/mixins/display-flex @display-flex
+ * @parent bit-docs-generate-html/theme/styles/mixins
  *
  * Sets the display to flex using vendor prefixes.
  *
@@ -133,8 +133,8 @@
 }
 
 /**
- * @property .flex-row
- * @parent bit-docs-generate-html/styles/mixins
+ * @property bit-docs-generate-html/theme/styles/mixins/flex-row @flex-row
+ * @parent bit-docs-generate-html/theme/styles/mixins
  *
  * Sets the display to flex and direction to row using vendor prefixes.
  *
@@ -160,8 +160,8 @@
 }
 
 /**
- * @property .flex-column
- * @parent bit-docs-generate-html/styles/mixins
+ * @property bit-docs-generate-html/theme/styles/mixins/flex-column @flex-column
+ * @parent bit-docs-generate-html/theme/styles/mixins
  *
  * Sets the display to flex and direction to column using vendor prefixes.
  *
@@ -187,8 +187,8 @@
 }
 
 /**
- * @property .flex-initial
- * @parent bit-docs-generate-html/styles/mixins
+ * @property bit-docs-generate-html/theme/styles/mixins/flex-initial @flex-initial
+ * @parent bit-docs-generate-html/theme/styles/mixins
  *
  * Emulates `flex: initial;` in a compatible way using vendor prefixes.
  *
@@ -207,8 +207,8 @@
 }
 
 /**
- * @property .flex-auto
- * @parent bit-docs-generate-html/styles/mixins
+ * @property bit-docs-generate-html/theme/styles/mixins/flex-auto @flex-auto
+ * @parent bit-docs-generate-html/theme/styles/mixins
  *
  * Emulates `flex: auto;` in a compatible way using vendor prefixes.
  *
@@ -227,8 +227,8 @@
 }
 
 /**
- * @property .flex-none
- * @parent bit-docs-generate-html/styles/mixins
+ * @property bit-docs-generate-html/theme/styles/mixins/flex-none @flex-none
+ * @parent bit-docs-generate-html/theme/styles/mixins
  *
  * Emulates `flex: none;` in a compatible way using vendor prefixes.
  *

site/default/static/styles/styles.less

@@ -1,8 +1,29 @@
 /**
- * @stylesheet styles.less Styles
- * @parent bit-docs/theme
+ * @parent bit-docs-generate-html/theme
+ * @page bit-docs-generate-html/theme/styles styles
  *
- * @description Styles for the generated site.
+ * @description The primary styles for the default theme.
+ *
+ * @body
+ *
+ * Styles are used to modify the visual representation of a generated website.
+ * 
+ * By default, `bit-docs` provides a very basic theme that consists of styles
+ * that are meant to be copied over to your project and/or a custom theme,
+ * and modified there as needed to suit your specific design needs.
+ * 
+ * The default `styles.less` is based on flexbox, and relies on two less files:
+ *
+ * - [bit-docs-generate-html/theme/styles/variables]
+ * - [bit-docs-generate-html/theme/styles/mixins]
+ *
+ * Any of these files can be copied over and modified as needed. For any less
+ * files not copied over, the default less file will be used.
+ * 
+ * Certain plugins provide their own less files for defining variables that
+ * are to be used in styling whatever they add, and will include your
+ * variables.less after their own so that you may override any less variables
+ * that you might wish to. A good example of this is [bit-docs-prettify].
  */
 
 @import "locate://bit-docs-site/styles/variables.less";
@@ -147,4 +168,4 @@ Desktop:
       overflow-y: auto;
     }
   }
-}
+}

site/default/static/styles/variables.less

@@ -1,26 +1,82 @@
 /**
-* @page bit-docs-generate-html/styles/variables Variables
-* @parent bit-docs-generate-html/styles
-*
-* @description Variables to hold site-wide visual configurations.
-*/
+ * @parent bit-docs-generate-html/theme/styles
+ * @page bit-docs-generate-html/theme/styles/variables variables
+ *
+ * @description Variables to hold site-wide visual configurations.
+ */
 
 /**
- * @option @defaultFontFamily The default font family.
+ * @property bit-docs-generate-html/theme/styles/variables/defaultFontFamily @defaultFontFamily
+ * @parent bit-docs-generate-html/theme/styles/variables
+ *
+ * The default font family.
+ *
+ * @body
+ *
+ * ### Use
+ *
+ * ```less
+ * body {
+ *   font-family: @defaultFontFamily;
+ * }
+ * ```
  */
 @defaultFontFamily: "Helvetica Neue-Light", "Helvetica Neue Light", "Helvetica Neue", Helvetica, Arial, "Lucida Grande", sans-serif;
 
 /**
- * @option @smartphones Media query breakpoint for smartphones.
+ * @property bit-docs-generate-html/theme/styles/variables/defaultPadding @defaultPadding
+ * @parent bit-docs-generate-html/theme/styles/variables
+ *
+ * Defualt padding for content containers.
+ *
+ * @body
+ *
+ * ### Use
+ *
+ * ```less
+ * body {
+ *   padding: @defaultPadding;
+ * }
+ * ```
  */
-@smartphones: ~"only screen and (max-width: 767px)";
+@defaultPadding: 25px;
 
 /**
- * @option @desktops Media query breakpoint for desktops.
+ * @property bit-docs-generate-html/theme/styles/variables/smartphones @smartphones
+ * @parent bit-docs-generate-html/theme/styles/variables
+ *
+ * Media query breakpoint for smartphones.
+ *
+ * @body
+ *
+ * ### Use
+ *
+ * ```less
+ * @@media @smartphones {
+ *   body {
+ *     font-size: 18px;
+ *   }
+ * }
+ * ```
  */
-@desktops: ~"only screen and (min-width: 767px)";
+@smartphones: ~"only screen and (max-width: 767px)";
 
 /**
- * @option @defaultPadding Defualt padding for content containers.
+ * @property bit-docs-generate-html/theme/styles/variables/desktops @desktops
+ * @parent bit-docs-generate-html/theme/styles/variables
+ *
+ * Media query breakpoint for desktops.
+ *
+ * @body
+ *
+ * ### Use
+ *
+ * ```less
+ * @@media @desktops {
+ *   body {
+ *     font-size: 12px;
+ *   }
+ * }
+ * ```
  */
-@defaultPadding: 25px;
+@desktops: ~"only screen and (min-width: 767px)";

site/default/templates/content.mustache.md

@@ -0,0 +1,38 @@
+@parent bit-docs-generate-html/theme/templates
+@page bit-docs-generate-html/theme/templates/content content
+
+@description The default content template.
+
+@body
+
+The `content.mustache` template includes other mustache files, by default:
+
+- `sidebar.mustache`
+- `title.mustache`
+- `description.mustache`
+- `body.mustache`
+
+Additionally, the template includes the main HTML markup.
+
+Copy this file into your own project or theme to modify HTML markup, or include
+other available templates.
+
+For instance, [bit-docs-js] provides the `signature.mustache` template that can
+be included to show a function signature in the generated output:
+
+```
+{{#unless hideBody}}
+    {{#if signatures}}
+        {{#each signatures}}
+            {{> signature.mustache}}
+        {{/each}}
+    {{else}}
+        {{#types}}
+            {{> signature.mustache}}
+        {{/types}}
+    {{/if}}
+    {{#if body}}
+        {{> body.mustache}}
+    {{/if}}
+{{/unless}}
+```

site/default/templates/templates.md

@@ -0,0 +1,28 @@
+@parent bit-docs-generate-html/theme
+@page bit-docs-generate-html/theme/templates templates
+
+@description Templates that come with the default theme.
+
+@body
+
+Templates are used by `bit-docs` to generate the output of a website.
+
+By default, `bit-docs` provides a very basic theme that consists of template
+files that are meant to be copied over to your project and/or a custom theme,
+and modified there as needed to suite your specific layout needs.
+
+The default templates do not make any assumptions about the type of website
+you are trying to generate. If you are generating documentation, you will
+probably want to add things like function signatures to the output of the
+generated website. That can be done by adding the `signature.mustache` to
+[bit-docs-generate-html/theme/templates/content].
+
+Other documentation that you might want to expose will come from the various
+[docObjects] in the [docMap], and you will need to create your own mustache
+templates as well as helpers to support that.
+
+Most users will be happy using the default output for documentation, and will
+primarily be editing the templates to add HTML markup for styling and
+structure purposes, in tandem with [bit-docs-generate-html/theme/styles].
+
+For any template files not copied over, the default template will be used.