Skip to content
Permalink
Browse files

Add annotations to main source files

  • Loading branch information...
thesephist committed Jan 13, 2019
1 parent 89d9f6b commit de5cfc47b40a2db95d5bcd6b24e4d78e67e3519c
Showing with 403 additions and 286 deletions.
  1. +19 −0 README.md
  2. +6 −2 docs/litterate.config.js.html
  3. +22 −14 docs/src/defaults.js.html
  4. +180 −163 docs/src/generate.js.html
  5. +112 −102 docs/src/index.js.html
  6. +4 −0 litterate.config.js
  7. +13 −2 src/defaults.js
  8. +34 −0 src/generate.js
  9. +13 −3 src/index.js
@@ -32,6 +32,8 @@ Description text for your project, shown in the generated site. You can use full

An array of file paths to annotate. You can specify file paths as full paths or [glob patterns](https://en.wikipedia.org/wiki/Glob_(programming)). On the main page of the generated site, links to individual files will show up in the order they're listed here.

By default, Litterate annotates all files that match `./src/**/*.js`.

### `wrap`

If 0, long lines of source code will never be wrapped. If any other number, Litterate will wrap long lines to the given number of characters per line.
@@ -48,6 +50,23 @@ Verbose output while Litterate runs, useful for debugging.

Specify a different destination directory for the generated docs site. By default, Litterate writes to `./docs/`.

### `annotationStartMark` and `annotationContinueMark`

By default, Litterate only counts comment blocks that look like this, as annotation blocks.

```javascript
//> Start of annotation block
// cotinued annotation block
function add(a, b) {
// comment that isn't counted
return a + b;
}
```

This allows you to write `// TODO` comments and other logistical comments without having them be parsed into Litterate annotations. If you'd rather use a different prefix to mark the start and subsequent lines of Litterate anotation blocks, you can override `annotationStartMark` (defaults to `//>`) and `annotationContinueMark` (defaults to `//`).

If you wanted to count all comments, for example, you could override `annotationStartMark` to `//`.

## Contributing

- `yarn install` to install dependencies (npm should work for these commands too, but the project prefers Yarn and we use a Yarn lockfile.)
@@ -23,8 +23,12 @@ <h1>./litterate.config.js <span class="fade">annotated source</span></h1>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">4</strong> description: '`litterate` is a tool to generate beautiful literate programming-style description of your code from comment annotations. Read more at [the GitHub repo](https://github.com/thesephist/litterate).',</pre></div>
<div class="line"><div class="doc"><p>We use GitHub Pages to host this generated site, which lives under a /litterate subdirectory</p>
</div><pre class="source javascript"><strong class="lineNumber">6</strong> baseURL: '/litterate',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">7</strong>}</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">8</strong></pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">7</strong> files: [</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">8</strong> './src/**/*.js',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">9</strong> './litterate.config.js',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">10</strong> ],</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">11</strong>}</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">12</strong></pre></div>
</main>
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/github-gist.min.css">
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/highlight.min.js"></script>
@@ -19,21 +19,29 @@ <h1>./src/defaults.js <span class="fade">annotated source</span></h1>
</div>
<div class="line"><div class="doc"><p>The default configuration file if the user doesn&#39;t specify a value for any options</p>
</div><pre class="source javascript"><strong class="lineNumber">3</strong>module.exports = {</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">4</strong> name: 'My Project',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">5</strong> description: 'Replace this description by setting the `description` option on `litterate`, or leave it blank',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">6</strong> wrap: 0, // don't wrap lines</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">7</strong> baseURL: '/',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">8</strong> verbose: false,</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">9</strong> files: [</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">10</strong> './src/**/*.js',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">11</strong> './litterate.config.js',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">12</strong> ],</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">4</strong></pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">5</strong> name: 'My Project',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">6</strong> description: 'Replace this description by setting the `description` option on `litterate`, or leave it blank',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">7</strong></pre></div>
<div class="line"><div class="doc"><p>Don&#39;t wrap lines</p>
</div><pre class="source javascript"><strong class="lineNumber">9</strong> wrap: 0,</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">10</strong></pre></div>
<div class="line"><div class="doc"><p>By default, it makes sense to assume that the root of the site is just <code>&#39;/&#39;</code></p>
</div><pre class="source javascript"><strong class="lineNumber">13</strong> baseURL: '/',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">14</strong> verbose: false,</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">15</strong></pre></div>
<div class="line"><div class="doc"><p>It&#39;s reasonable to assume that most projects keep the main source files in <code>./src/</code>, so that&#39;s the default files option. We may reverse this call in the future though to be blank by default.</p>
</div><pre class="source javascript"><strong class="lineNumber">19</strong> files: [</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">20</strong> './src/**/*.js',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">21</strong> ],</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">22</strong></pre></div>
<div class="line"><div class="doc"><p>We default to this because this is where GitHub Pages pulls from.</p>
</div><pre class="source javascript"><strong class="lineNumber">14</strong> outputDirectory: './docs/',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">15</strong> annotationStartMark: '//&#62;',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">16</strong> annotationContinueMark: '//',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">17</strong>}</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">18</strong></pre></div>
</div><pre class="source javascript"><strong class="lineNumber">24</strong> outputDirectory: './docs/',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">25</strong></pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">26</strong> annotationStartMark: '//&#62;',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">27</strong> annotationContinueMark: '//',</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">28</strong>}</pre></div>
<div class="line"><div class="doc"></div><pre class="source javascript"><strong class="lineNumber">29</strong></pre></div>
</main>
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/styles/github-gist.min.css">
<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.13.1/highlight.min.js"></script>

0 comments on commit de5cfc4

Please sign in to comment.
You can’t perform that action at this time.