{ "parser": "YUIDoc", "name": "ember-fountainhead", "description": "Robust interactive documentation for your Ember application's source code", "version": "3.2.0", "repository": "https://github.com/healthsparq/ember-fountainhead", "guides": [ { "attributes": { "id": "getting-started", "linkText": "Getting Started", "title": "Getting Started" }, "body": "{{#fountainhead-header tagName=\"h2\" elementId=\"installation\"}}Installation{{/fountainhead-header}}\n

Install Ember Fountainhead using Ember CLI:

\n

ember install ember-fountainhead

\n

{{#fountainhead-alert brand='info' dismiss=false}}\n{{fountainhead-svg svgId='info'}}Fountainhead's target Node version is the active LTS,\nas recommended by Ember. Using Fountainhead on previous versions may not be possible.\n{{/fountainhead-alert}}

\n

* Currently Ember Fountainhead must be used inside of an Ember application.

\n{{#fountainhead-header tagName=\"h2\" elementId=\"documentation-generation\"}}Documentation Generation{{/fountainhead-header}}\n

If you already have YUIDoc documentation comments block (DocBlocks) in your\nsource code, you can generate Fountainhead documentation data files with the\ncommand ember docs.

\n

By default Fountainhead will generate data files any time you build your app,\nas well as rebuild the files any time your app changes. This can be disabled\nusing the liveEdit configuration.

\n

If you don't have DocBlock comments to your source code, you can start adding\nthem. Fountainhead uses YUIDoc for\nsource code DocBlock parsing. YUIDoc uses a syntax similar to JSDoc, but does not\nparse your source code, only the comments.

\n

See YUIDoc Syntax for details\non YUIDoc tags.

\n{{#fountainhead-header tagName=\"h2\" elementId=\"excluding-from-production\"}}Excluding from Production{{/fountainhead-header}}\n

To exclude Fountainhead from your production builds you can blacklist in your\nember-cli-build configuration using the addons.blacklist array:

\n
ember-cli-build.js
\n
module.exports = function(defaults) {\n  var app = new EmberApp(defaults, {\n    addons: {\n      blacklist: EmberApp.env() === 'production' ? ['ember-fountainhead'] : []\n    }\n  });\n\n  return app.toTree();\n};\n
\n\n
\n{{#fountainhead-header tagName=\"h2\" elementId=\"configuration\"}}Configuration{{/fountainhead-header}}\n

The Ember Fountainhead addon as well as the data file generation process can\nbe configured in a fountainhead.js file located in your repo's root:

\n
fountainhead.js
\n
module.exports = {\n  entry: ['app'], // Defaults to 'app' for apps and 'addon' for addons\n  output: {\n    path: 'docs' // path to save generated docs to\n    filename: 'fountainhead-data.json' // name to save generated file to\n  }\n}\n
\n

{{#fountainhead-alert brand='info' dismiss=false}}\n{{fountainhead-svg svgId='info'}}See {{link-to 'Configuring Fountainhead' 'guides' 'configuration'}}\nfor all possible configuration options.\n{{/fountainhead-alert}}

\n{{#fountainhead-header tagName=\"h2\" elementId=\"addon-styles\"}}Addon Styles{{/fountainhead-header}}\n

Ember Fountainhead's styles are bundled into your vendor.css by\ndefault. The styles are scoped to addon namespaces to prevent conflicts with\nyour application's styles. You can disable style sheet bundling by setting\nincludeVendorStyles to false in your fountainhead.js configuration file.

\n

If you'd like to extend Fountainhead's styles and your project uses SASS, you\ncan turn off the auto bundle to the vendor file and directly import Fountainhead\ninto your SASS: @import 'ember-fountainhead'

\n

See the themes\nfor variables you can override.

\n{{#fountainhead-header tagName=\"h2\" elementId=\"ember-component-playground\"}}Ember Component Playground{{/fountainhead-header}}\n

The Ember Component Playground\naddon is a great compliment to this addon that allows real time examples of\ncomponents. See the repo for installation.

\n", "frontmatter": "id: getting-started\nlinkText: Getting Started\ntitle: Getting Started", "id": "getting-started", "type": "guides" }, { "attributes": { "id": "configuration", "linkText": "Configuring Fountainhead", "title": "Configuring Fountainhead" }, "body": "

Fountainhead has sane defaults for all configuration options. Standard apps/addons\nshould be able to generate documentation files and use Fountainhead without any\nconfiguration. When needed though, Fountainhead can be customized as desired using\na fountainhead.js file.

\n{{#fountainhead-header tagName=\"h2\" elementId=\"fountainhead.js-configuration-options\"}}fountainhead.js Configuration Options{{/fountainhead-header}}\n
fountainhead.js
\n
/*\n * Fountainhead Default Configurations\n * These are the configuration defaults, they can be overwritten as needed\n */\nmodule.exports = {\n  // Sets url for repository link in top left of API page\n  repository: ''\n  // Generate data files before builds for live reloading\n  liveEdit: true,\n  // Import Fountainhead styles into vendor.css\n  includeVendorStyles: true,\n  // Set to true to suppress error logging during data file generation\n  quiet: false,\n  // Fountainhead custom tags not recognized by YUIDoc\n  whiteListTags: ['passed', 'closure', 'action'],\n  // Set custom logo path\n  logo: ''\n  // Directories to parse for API documentation\n  entry: ['app'],\n  // Paths to guide files\n  guides: [],\n  // Output directory and filename for master data set\n  output: {\n    filename: 'fountainhead-data.json',\n    path: path.resolve('docs')\n  },\n  // Automatically set to consuming application's locationType, but can\n  // be explicitly specified (sets internal link id target types between\n  // query params and hash fragments)\n  locationType: locationType\n};\n
\n

{{#fountainhead-alert canDismiss=false brand='info'}}\n{{fountainhead-svg svgId='info'}} All paths are resolved using path.resolve,\nmeaning that either a relative path or paths starting with ./ will resolve to\nyour project's root directory.\n{{/fountainhead-alert}}

\n{{#fountainhead-header tagName=\"h2\" elementId=\"environment-specific-configuration\"}}Environment Specific Configuration{{/fountainhead-header}}\n

You can export a function from fountainhead.js that will receive the build\nenvironment as a parameter if you need environment specific configurations:

\n
fountainhead.js
\n
// EG: Include only your app files for production documentation. In dev builds\n// include internal dev utilities documentation\nmodule.exports = env => {\n  entry: env === 'production' ? ['app'] : ['app', 'dev-utilities']\n}\n
\n{{#fountainhead-header tagName=\"h2\" elementId=\"fountainhead-service-namespace\"}}Fountainhead Service Namespace{{/fountainhead-header}}\n

You can override the root namespace that all Fountainhead requests use by setting\nthe {{c-l class='Fountainhead' item='apiNamespace'}}. The default value is /docs.

\n
app.js
\n
import Fountainhead from 'ember-fountainhead/services/fountainhead';\n\nFountainhead.reopen({ apiNamespace: '/special-namespace/v1/' });\n
\n

The meta request would now use url: /special-namespace/v1/meta.json

\n", "frontmatter": "id: configuration\nlinkText: Configuring Fountainhead\ntitle: Configuring Fountainhead", "id": "configuration", "type": "guides" }, { "attributes": { "id": "writing-guides", "linkText": "Writing Guides", "title": "Writing Guides with Ember Fountainhead" }, "body": "

Fountainhead makes writing guides easy with these features:

\n\n

We hope that these conveniences inspire you to write guides for your project!\nSemantically named variables and methods go a long way towards self documenting code,\nand API documentation helps for reference, but guides bridge the gap of providing\nproject overviews, architecture considerations and the why of code. For\ncontributors looking to get started with projects, these aspects can be really hard\nto deciper without a guide!

\n{{#fountainhead-header tagName=\"h2\" elementId=\"guide-discovery\"}}Guide Discovery{{/fountainhead-header}}\n

There are two ways Fountainhead can be configured to consume guides:

\n
    \n
  1. Automatically, by saving the guide in /guides
    2. \n
  2. Explicitly, by configuring the file path in the fountainhead.guides config.
    3. \n
\n{{#fountainhead-header tagName=\"h4\" elementId=\"automatic-discovery\"}}Automatic Discovery{{/fountainhead-header}}\n

Fountainhead will automatically consume any guide that is saved in /guides. The\nguides will be consumed alphabetically by file path+name and the order of guides in\nthe the navbar will match this order. See Ordering Guides\n for info on controlling the guide display order.

\n{{#fountainhead-header tagName=\"h4\" elementId=\"explicit-configuration\"}}Explicit Configuration{{/fountainhead-header}}\n

Guides from any location in your project can be consumed using the\nfountainhead.guides config in your fountainhead.js config file. Guides must be an\narray and can include paths to files or directories.

\n

{{#fountainhead-alert canDismiss=false brand='info'}}\n{{fountainhead-svg svgId='info'}} PRO TIP
\nYou can create domain specific guides in your project source and include them in your\ndocumentation using the guides config. This can be especially helpful\nfor project features that require architecture/background knowledge that doesn't\nfit explicitly into the API documentation.\n{{/fountainhead-alert}}

\n

For example, this project has all of the setup and how-to guides in the /guides\ndirectory, but is also configured to include Release guides and an architecture\noverview of scroll targeting using the guides config:

\n
fountainhead.js
\n
module.exports = {\n  guides: [\n    'addon/scroll-target.md', // Specific file in the addon directory\n    'releases' // Folder of release guides in project root\n  ],\n}\n
\n{{#fountainhead-header tagName=\"h2\" elementId=\"adding-meta-data\"}}Adding Meta Data{{/fountainhead-header}}\n

You can include a front matter block in\na guide to easily configure meta data for the guide. The following configurations\ncan be used to control how your guide is displayed:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
AttributeUse
idRequiredUnique identifier for a guide. Also used as the url model id
[linkText]OptionalAnchor text used in guide navigation
[title]OptionalPage header text
[group]OptionalParent label to nest a set of groups under
[private]OptionalWhen true, guide is not parsed or included in nav
[protected]OptionalWhen true, guide is parsed and saved, but not included in meta
\n
your-guide.md
\n
---\nid: writing-guides\nlinkText: Writing Guides\ntitle: Writing Guides with Ember Fountainhead\ngroup: How Tos\n---\n\nEmber Fountainhead makes writing guides easy...\n
\n{{#fountainhead-header tagName=\"h4\" elementId=\"guide-access\"}}Guide Access{{/fountainhead-header}}\n

The private and protected meta attributes can be used to control what guides are\nconsumed and displayed by Fountainhead.

\n\n{{#fountainhead-header tagName=\"h2\" elementId=\"grouping-guides\"}}Grouping Guides{{/fountainhead-header}}\n

Sets of guides can be grouped together in the guide navigation using a group\nattribute. This is useful if you have a set of guides that are related, but too long\nto contain in a single guide. You can create groups for your guides in two ways:

\n
    \n
  1. On the fly: Include a group attribute in any guide. If that group doesn't exist\nFountainhead will create one and add that group to it.
    2. \n
  2. Explicitly: Groups can be configured in the fountainhead.guides config (This\ncan be helfpul for guide ordering):
    3. \n
\n
  module.exports = {\n    guides: [\n      { id: 'How Tos' }, // Object literals are interpreted as a group config\n    ],\n  }\n
\n{{#fountainhead-header tagName=\"h4\" elementId=\"ordering-guides\"}}Ordering Guides{{/fountainhead-header}}\n

Guides are included in the guide navigation in this order:

\n
    \n
  1. Guides auto discovered in /guides alphabetically by filepath+name
    2. \n
  2. Configured order of fountainhead.guides configuration array
    3. \n
\n

If you want to control the order of the guides listed in the navigation, you can use\nordered file names and folders, eg: 1_first-guide.md, 2_second-guide.md. See the\nguides directory\nfor Fountainhead for a complex example.

\n", "frontmatter": "id: writing-guides\nlinkText: Writing Guides\ntitle: Writing Guides with Ember Fountainhead", "id": "writing-guides", "type": "guides" }, { "attributes": { "id": "tools", "linkText": "Fountainhead Tools", "title": "Fountainhead Documentation Tools and Features" }, "body": "

Fountainhead isn't just about writing beautiful documentation. Fountainhead\ncomes with a set of tools for writing interactive documentation.

\n{{#fountainhead-header tagName=\"h2\" elementId=\"runtime-template-compilation\"}}Runtime Template Compilation{{/fountainhead-header}}\n

All DocBlock descriptions and guides are compiled to template partials during\nruntime. This lets you use any component available in your app into your descriptions.\nThis means that you're not limited to a predefined set of documentation components\npre-bundled with some library. Want to make a custom drawer component for rendering\nexamples of property values? With Fountainhead all you have to do is add the\ncomponent to your application and use it in a DocBlock.

\n{{#fountainhead-header tagName=\"h2\" elementId=\"crosslink-component\"}}CrossLink Component{{/fountainhead-header}}\n

Use the {{c-l class='CrossLink'}} component to reference modules, classes, methods\nand properties elsewhere in your documentation:

\n
/**\n * DocBlock for some class, with a direct link to the \\{{c-l 'init'}} method.\n * @property active\n * @type {boolean}\n */\n
\n

{{#c-l class='CrossLink'}}See the CrossLink Component for examples.{{/c-l}}

\n{{#fountainhead-header tagName=\"h2\" elementId=\"state-in-docblock-descriptions\"}}State in DocBlock Descriptions{{/fountainhead-header}}\n

Your documentation descriptions are wrapped in an instance of\nEmber Radical's rad-state\nfor a convenient and sandboxed state property and state actions. This is\nconvenient for including examples in your documentation that require simple\nstate management.

\n

Use state to access the sandboxed state and any of stateActions.open,\nstateActions.close and stateActions.toggleState to mutate the state.

\n{{#fountainhead-header tagName=\"h2\" elementId=\"glimmer-code-blocks\"}}Glimmer Code Blocks{{/fountainhead-header}}\n

Use the identifier glimmer with a fenced code block to highlight the code block\ncontents and render an unescaped example of the code block immediately after\nthe code block.

\n

Eg, the following code block:

\n
```glimmer\n  \\{{some-component example=true}}\n```\n
\n

Will actually be parsed as:

\n
```glimmer\n  \\{{some-component example=true}}\n```\n{{some-component example=true}}\n
\n

You can also add data when rendering you components, this is super useful for showing\nvariations of a theme or components in different states.

\n

At the top of your glimmer add data using a JSON string\ne.g. data={'things': ['primary', 'secondary', 'success']}. This will make every top level key available\nto your example and will be stripped from the displayed code.

\n

You can then use the properties in the template.

\n
{{#each colors as |color|}}\n  {{#fountainhead-button brand=color}}{{color}}{{/fountainhead-button}}\n{{/each}}\n
\n

data={\"colors\": [\"primary\", \"secondary\", \"success\"]}\n{{#each colors as |color|}}\n{{#fountainhead-button brand=color}}{{color}}{{/fountainhead-button}}\n{{/each}}

\n{{#fountainhead-header tagName=\"h2\" elementId=\"markdown-in-docblock-descriptions-and-guides\"}}Markdown in DocBlock Descriptions and Guides{{/fountainhead-header}}\n

Fountainhead has full support for markdown in documentation blocks and guides.\nIf you're not familiar with markdown, you can start with a tutorial at\nMarkdown Tutorial

\n

(Markdown is parsed using markdown-it)

\n", "frontmatter": "id: tools\nlinkText: Fountainhead Tools\ntitle: Fountainhead Documentation Tools and Features", "id": "tools", "type": "guides" }, { "id": "Architecture", "linkText": "Architecture", "guideGroup": true, "type": "guides", "guides": [ { "attributes": { "id": "scroll-targeting", "linkText": "Scroll Targets", "title": "Automatic Scrolling and Click To Copy Headers", "group": "Architecture" }, "body": "

Fountainhead has different automatic scrolling to header and property ids for Hash\nLocation consumers and History Location consumers. The goal of this is to offer very\nclean URLs for consumers using history location routing, while still supporting targeted\nscrolling for consumers using hash location routing. History routing consumers will\ngenerate URLs with fragment ids. Hash routing consumers will generate URLs with id\nquery params:

\n

History Location Routing:
\nyour-docs.com/guides/your-guide#header-id
\nHash Location Routing:
\nyour-docs.com/#/guides/your-guide?id=header-id

\n{{#fountainhead-header tagName=\"h2\" elementId=\"feature-overview\"}}Feature Overview{{/fountainhead-header}}\n

If you need to make an update or log a bug against the feature this overview will\nprovide background information on how the overall flow executes.

\n
    \n
  1. Addon index.js reads consuming application's locationType in addon config\nhook. The locationType is passed into every call to generate documentation data.\nIn data generation, if the locationType is hash, the flag hashRouting is\nset to true and added to the documentation meta. (History routing is the\ndefault routing expected. hashRouting is only set as an override)
    2. \n
  2. Addon begins tracking the location hash in order to pass the hash down as a data\nelement. Routes /api and /guides activate hook trigger the fountainhead\nservice to set an event listener for the hashchange event. This event fires\nanytime an in page url with a hash fragment is clicked. All routes will reset the\ntracked fragment id and then update it after the url changes (Required due to\nroute changes not firing the hashChange event).
    3. \n
  3. Routes will reset the page scroll to the top on every transition. This ensures\nthat if the page is scrolled, and the new route doesn't have a scroll target, the\npage is correctly scrolled to the top.
    4. \n
  4. Page templates pass either the tracked hash fragment or the controller id query\nparam to page components depending on the consuming routing type.
    5. \n
  5. Any change in the model or passed scroll target will trigger the page's\ndidReceiveAttrs hook, which is used to scroll to the passed target, or scroll to\ntop of page if no target is present.
    6. \n
  6. Headers and property links are wrapped in either an anchor with the href set to a\nfragment id for history location consumers or a link-to with the id query param\nfor hash location users.
    7. \n
\n{{#fountainhead-header tagName=\"h2\" elementId=\"feature-overview-ii\"}}Feature Overview II{{/fountainhead-header}}\n
    \n
  1. Addon checks if consumer is using Hash or History location, updates Fountainhead's\ndocumentation meta with flag.
    2. \n
  2. IF HASH => Use query params, and everything will Just Work™. Router, link-tos and\ncontrollers automatically track id query param. Passed down into page components\nwe can use didReceiveAttrs hook to execute scrolling.
    3. \n
  3. IF HISTORY => Hash has to be tracked:\n\n
    4. \n
  4. On route activation, send trackHash, creates new listener for hash change AND\nsets current hash if one has been set (this is how page reload still triggers a\na scroll).
    5. \n
  5. Clicking an anchor with fragment ONLY will fire a hash change event, but clicking\na link-to to a different route OR clicking browser back button will NOT fire a\nhash change event.
    6. \n
  6. For route changes:\n\n
    7. \n
\n", "frontmatter": "id: scroll-targeting\nlinkText: Scroll Targets\ntitle: Automatic Scrolling and Click To Copy Headers\ngroup: Architecture", "id": "scroll-targeting", "type": "guides" } ] }, { "attributes": { "id": "releases", "linkText": "Releases", "title": "Release Notes" }, "body": "
\n {{#link-to 'guides' 'v4.0.0-guides-update'}}\n

v4.0.0 Guides Enhancements

\n {{/link-to}}\n
\n

Fountainhead v4 is focused on enhancing the guides feature. API documentation is\nimportant for end consumers of any library or application, but we think that guides\nhelp contributors and maintainers more than any resource. How many times have you\nwanted to contribute to a project, but then spent hours trying to decipher how the\nproject is structured, how…

\n", "frontmatter": "id: releases\nlinkText: Releases\ntitle: Release Notes", "id": "releases", "type": "guides" } ], "modules": [ { "name": "Addon", "type": "modules" }, { "name": "App", "type": "modules" }, { "name": "Blueprints", "type": "modules" }, { "name": "Lib", "type": "modules" } ], "classes": [ { "name": "API", "type": "classes" }, { "name": "API.Classes", "type": "classes" }, { "name": "API.Files", "type": "classes" }, { "name": "API.Modules", "type": "classes" }, { "name": "BaseController", "type": "classes" }, { "name": "BaseRoute", "type": "classes" }, { "name": "CrossLink", "type": "classes" }, { "name": "DataTypes.GenerateClasses", "type": "classes" }, { "name": "DataTypes.GenerateGuide", "type": "classes" }, { "name": "DataTypes.GenerateModules", "type": "classes" }, { "name": "DataTypes.GenerateSrcFile", "type": "classes" }, { "name": "Docs.Classes", "type": "classes" }, { "name": "Docs.Files", "type": "classes" }, { "name": "Docs.Modules", "type": "classes" }, { "name": "EmberFountainhead.Index", "type": "classes" }, { "name": "FHHref", "type": "classes" }, { "name": "FounatianheadHeader", "type": "classes" }, { "name": "FountaineadClass.Header", "type": "classes" }, { "name": "FountaineadClass.Item", "type": "classes" }, { "name": "Fountainhead", "type": "classes" }, { "name": "FountainheadAlert", "type": "classes" }, { "name": "FountainheadButton", "type": "classes" }, { "name": "FountainheadClass.ItemsContainer", "type": "classes" }, { "name": "FountainheadClass.Meta", "type": "classes" }, { "name": "FountainheadClass.PropertyLink", "type": "classes" }, { "name": "FountainheadGetStarted", "type": "classes" }, { "name": "FountainheadPages.API", "type": "classes" }, { "name": "FountainheadPages.APIIndex", "type": "classes" }, { "name": "FountainheadPages.BasePage", "type": "classes" }, { "name": "FountainheadPages.Class", "type": "classes" }, { "name": "FountainheadPages.File", "type": "classes" }, { "name": "FountainheadPages.Guide", "type": "classes" }, { "name": "FountainheadPages.Module", "type": "classes" }, { "name": "FountainheadRepoLink", "type": "classes" }, { "name": "FountainheadRoutes", "type": "classes" }, { "name": "FountainheadRuntimeDescription", "type": "classes" }, { "name": "FountainheadSVG", "type": "classes" }, { "name": "FountainheadState", "type": "classes" }, { "name": "FountainheadTabs", "type": "classes" }, { "name": "FountainheadTabsContent", "type": "classes" }, { "name": "FountainheadWelcome", "type": "classes" }, { "name": "Guides", "type": "classes" }, { "name": "Helper.Eq", "type": "classes" }, { "name": "Index", "type": "classes" }, { "name": "NavigationAPI", "type": "classes" }, { "name": "NavigationAPI.Logo", "type": "classes" }, { "name": "NavigationAPI.SearchBar", "type": "classes" }, { "name": "NavigationAPI.Section", "type": "classes" }, { "name": "NavigationGuides", "type": "classes" }, { "name": "createDirs", "type": "classes" }, { "name": "decorateConfig", "type": "classes" }, { "name": "generateFountainheadData", "type": "classes" }, { "name": "logger", "type": "classes" }, { "name": "parseMarkdown", "type": "classes" }, { "name": "readDirRecursive", "type": "classes" } ] }