documon
Version:
A documentation system for mortals. Use with any language.
1,481 lines (767 loc) • 51.8 kB
HTML
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>documon</title>
<meta name="description" content="The main entry point and processor for Documon, which allows you to run Documon directly from Node.">
<!-- Normalize -->
<link rel="stylesheet" href="assets/vendor/normalize.css">
<!-- prettify -->
<link rel="stylesheet" href="assets/vendor/prettify/codamike.css">
<script src="assets/vendor/prettify/prettify.js"></script>
<!-- Documon Pages Info. (Used by various classes to identify this page.) -->
<script>
var pageCtx = {
id : "documon.documon",
name: "documon"
}
</script>
<!-- theme
<link rel="stylesheet" href="assets/fonts/Fira_Sans/FiraSans.css">
<link rel="stylesheet" href="assets/fonts/Inconsolata/inconsolata.css">
-->
<link rel="stylesheet" href="assets/css/pages.css">
<script src="assets/js/documon/Storage.js"></script>
<script src="assets/js/documon/Access.js"></script>
<script src="assets/js/documon/Pages.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-106684927-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body>
<div class="page">
<div class="main-method">
<a name="methods"></a>
<div class="part-methods">
<a name="documon.documon"></a><a name="documon"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
documon ()
</span>
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span>
<span class="member-line-number">26</span>
</span>
</div>
<div class="member-description">
<div class="meta-block meta-block-klass">
<div class="meta-line"><span class="meta-label" >xpath</span> <span class="meta-target">documon.documon<span></div>
<div class="meta-line"><span class="meta-label" >file</span> <span class="meta-target">documon/src/documon.js<span></div>
</div>
<p>The main entry point and processor for Documon, which allows you to run Documon directly from Node.</p>
<div class="member">
<div class="heading-example">Example</div>
<div class="example-block">
<pre><code> var myDocumon = require("path/to/documon/src/documon.js");
myDocumon.run({
files : "path/to/src"
});</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="parts">
<a name="properties"></a>
<div class="part-properties">
<div class="heading-part">Properties</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<a name="documon.documon.dumpData"></a><a name="dumpData"></a>
<span class="member-name">dumpData</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span><span class="member-line-number" title="documon/src/documon.js">120</span>
</span>
<div class="param-description">
<span class="type">boolean</span>
<span class="default-value">
false
</span>
<div class="member-description">
<p>Whether or not to write intermediary files used during processing to the output data folder.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<a name="documon.documon.extensions"></a><a name="extensions"></a>
<span class="member-name">extensions</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span><span class="member-line-number" title="documon/src/documon.js">86</span>
</span>
<div class="param-description">
<span class="type">array</span>
<div class="member-description">
<p>The list of extensions to search for source code.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<a name="documon.documon.ignoreList"></a><a name="ignoreList"></a>
<span class="member-name">ignoreList</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span><span class="member-line-number" title="documon/src/documon.js">97</span>
</span>
<div class="param-description">
<span class="type">array</span>
<div class="member-description">
<p>A list of strings representing regex patterns for files/folders to ignore. By default the following patterns are already included:</p>
<pre><code> '\/\.'
'\.git'
'node_modules'
Configuration will concat this list with the user provied list.</code></pre>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<a name="documon.documon.indexRedirectName"></a><a name="indexRedirectName"></a>
<span class="member-name">indexRedirectName</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span><span class="member-line-number" title="documon/src/documon.js">125</span>
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The filename for the shortcut to the index.html file. Use a name that will push the name to the top of the folder for quicker access to the index.hrml file.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<a name="documon.documon.mainConf"></a><a name="mainConf"></a>
<span class="member-name">mainConf</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span><span class="member-line-number" title="documon/src/documon.js">81</span>
</span>
<div class="param-description">
<span class="type">Object</span>
<div class="member-description">
<p>NOTE: // sourceRootFolder and dataFolder are injected into the "mainConf" by documon.</p>
<p>Example link <a href="root.documon.dirutils.makedir">other class to root.documon.dirutils.makedir</a><br />
Example link <a href="documon.dirutils.makedir">other class to documon.dirutils.makedir</a><br />
Example link <a href="documon.dirutils">other class to documon.dirutils</a><br />
Example link <a href="#run">local to #run</a></p>
</div>
<div class="part-parameters">
<div class="heading-part">mainConf properties</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">projectName</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The title of the project (displayed in the title of the docs).</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">files</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string | array</span>
<div class="member-description">
<p>The location of the source file or folder to process.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">outputFolder</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>Where the docs will be written to. Defaults to be parallel to source folder.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">ignoreList</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">array</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>A list of source files or folders to ignore.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">templateFolder</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>The path to the template folder (defaults to the main documon/template folder)</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">projectVersion</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>Your product's version</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">docBegin</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<span class="default-value">
/**
</span>
<div class="member-description">
<p>Delimiter used to signify the START of a source-code comment.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">docEnd</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<span class="default-value">
*/
</span>
<div class="member-description">
<p>Delimiter used to signify the END of a source-code comment.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">launchWhenDone</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">boolean</span>
<span class="flag optional">optional</span>
<span class="default-value">
false
</span>
<div class="member-description">
<p>Launch the documentation in the browser when done?</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">sourceExt</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string | array</span>
<span class="flag optional">optional</span>
<span class="default-value">
js
</span>
<div class="member-description">
<p>The extension of your source code files to parse. For multiple kinds, use a space delimited string (e.g. "js jsx py php").</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">dumpData</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">boolean</span>
<span class="flag optional">optional</span>
<span class="default-value">
false
</span>
<div class="member-description">
<p>Whether or not to save intermediary data objects.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">docsDirName</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">String</span>
<span class="flag optional">optional</span>
<span class="default-value">
docs
</span>
<div class="member-description">
<p>The folder name used to house the docs.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">sourceRootFolder</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">String</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>(derived by documon) The actual location that a given source file resides within.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">dataFolder</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">String</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>(derived by documon) The path used to place data files.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">more</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">String</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>The path to a folder containing addition markdown (.md) files to include.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">indexShortcutName</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">String</span>
<span class="flag optional">optional</span>
<span class="default-value">
__LAUNCH.html
</span>
<div class="member-description">
<p>The name of the index shortcut file to push it to the top of the folder so you don't have to scroll and hunt andpeck for hte "index.html" file to launch the docs.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">moreQuirkDelimiter</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">String</span>
<span class="flag optional">optional</span>
<span class="default-value">
.
</span>
<div class="member-description">
<p>More quirk delimiter. The character(s) use to seperate the "more" page numbering system from page titles.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<a name="documon.documon.quiet"></a><a name="quiet"></a>
<span class="member-name">quiet</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span><span class="member-line-number" title="documon/src/documon.js">115</span>
</span>
<div class="param-description">
<span class="type">boolean</span>
<span class="default-value">
false
</span>
<div class="member-description">
<p>Supress stdout messages.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<a name="methods"></a>
<div class="part-methods">
<div class="heading-part">Methods</div>
<a name="documon.documon.filterFileTypes"></a><a name="filterFileTypes"></a>
<div class="member" data-access="private" >
<div class="member-name clearfix">
<span class="member-name-left">
filterFileTypes (<span class="method-arguments">fpath</span>)
<span class="flag private">private</span> <!-- public private protected -->
</span>
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span>
<span class="member-line-number">152</span>
</span>
</div>
<div class="member-description">
<p>Determines if the file has the proper extension based on the acceptable extensions defined in this modules static "extensions" array.</p>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">fpath</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path or full file name.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">boolean</span>
</div>
<div class="member"><p>Whether or not it's an OK extension.</p></div>
</div>
</div>
<a name="documon.documon.init"></a><a name="init"></a>
<div class="member" data-access="private" >
<div class="member-name clearfix">
<span class="member-name-left">
init (<span class="method-arguments">conf</span>)
<span class="flag private">private</span> <!-- public private protected -->
</span>
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span>
<span class="member-line-number">188</span>
</span>
</div>
<div class="member-description">
<p>Initializes Documan based on the configuration settings</p>
<ul>
<li>Parses configuration</li>
<li>Finds source files</li>
<li>Creates output folder</li>
<li>Copies template assets to output folder</li>
<li>Initializes main templates</li>
</ul>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">conf</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">object</span>
<div class="member-description">
<p>See (run)[run], as this configuration object is simply passed through.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">boolean</span>
</div>
<div class="member"><p>False when there's an error or misconfiguration. True when everything seems cool.</p></div>
</div>
</div>
<a name="documon.documon.run"></a><a name="run"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
run (<span class="method-arguments">conf</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span>
<span class="member-line-number">623</span>
</span>
</div>
<div class="member-description">
<p>The main processing loop that executes and manages the main flow control of parsing, evaluating and <br />
construction of the documentation.</p>
<p>After <a href="#init">init</a> configures things based on the settings, and generates a list of files to process<br />
this method process and sends each file to the <a href="#seeder">seeder</a> of evaluation and processing.</p>
<ul>
<li>Generates HTML pages</li>
<li>Generates _menuData.js</li>
</ul>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">conf</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">object</span>
<div class="member-description">
<p>The configuration object. See <a href="#mainConf">mainConf</a></p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<a name="documon.documon.seeder"></a><a name="seeder"></a>
<div class="member" data-access="private" >
<div class="member-name clearfix">
<span class="member-name-left">
seeder (<span class="method-arguments">file</span>)
<span class="flag private">private</span> <!-- public private protected -->
</span>
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span>
<span class="member-line-number">517</span>
</span>
</div>
<div class="member-description">
<p>Extracts, parses and tags comments from one source file and stuffs the result into <a href="#organizer">organizer</a>.</p>
<ul>
<li>Generates data files (if dumpData enabled)</li>
</ul>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">file</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to the file.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">object</span>
</div>
<div class="member"><p>The file's search data as computed by tag.js</p></div>
</div>
</div>
<a name="documon.documon.shouldIgnore"></a><a name="shouldIgnore"></a>
<div class="member" data-access="private" >
<div class="member-name clearfix">
<span class="member-name-left">
shouldIgnore (<span class="method-arguments">item</span>)
<span class="flag private">private</span> <!-- public private protected -->
</span>
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span>
<span class="member-line-number">475</span>
</span>
</div>
<div class="member-description">
<p>Extracts, parses and tags comments from one source file and stuffs the result into <a href="#organizer">organizer</a>.</p>
<ul>
<li>Generates data files (if dumpData enabled)</li>
</ul>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">item</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to the file.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">boolean</span>
</div>
<div class="member"><p>true = ignore this file, false = don't ignore.</p></div>
</div>
</div>
<a name="documon.documon.writeData"></a><a name="writeData"></a>
<div class="member" data-access="private" >
<div class="member-name clearfix">
<span class="member-name-left">
writeData (<span class="method-arguments">fpath</span>, <span class="method-arguments">data</span>, <span class="method-arguments">json</span>)
<span class="flag private">private</span> <!-- public private protected -->
</span>
<span class="member-name-right">
<span class="member-file">documon/src/documon.js</span>
<span class="member-line-number">141</span>
</span>
</div>
<div class="member-description">
<p>Simplify file write for text or json.</p>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">fpath</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to save to.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">data</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>