docco-husky

2019-09-13

Generated static project documentation primarily for node.js projects. A fork of Docco

Overview

A streamlined static site generator for project documentation based on Docco. "Husky" because it's bigger and more irregular than Docco, like HuskyJeans you would buy at Sears back in the day.

A fork of Docco, intended to go beyond the appropriate scope of Docco itself. Forked because Docco itself is pretty simple and this is intended to diverge. The initial fork included merged pull requests from nevirand jswartwoodfor their work on supporting recursive directories and an improved "Jump To" menu.

Examples

Check out the generated documentationfor this project.

Or these other samples

Installation

Possible Gotchas

  • Docco requires Pygmentsto be installed and will try to install it if it's not already.
  • Perl is required for cloc

To install via npm into your project:

npm install docco-husky

Install globally:

[sudo] npm install -g docco-husky

Or include as a dependency in your package.json

Generating Documentation

docco-husky will generate docs in a ./docs directory. It accepts multiple files (including wildcards) and directories for it to recurse.

docco-husky -name "<optional project name>" <list of files>

Optional configuration in your package.json. The project name can alternatively be passed in the package.json configuration and it will override the value passed in the -nameoption.

"docco_husky": {
    "css": "path/to/alternative/css/file.css"
    "output_dir": "docs/out",                    // default "docs"
    "content_dir": "docs/my_markdown_files",    // default null
    "project_name": "Your Project name",
    "show_timestamp": true                      // default true
  }

Examples

# from a local install
./node_modules/.bin/docco-husky app.js lib public

# with a project name
./node_modules/.bin/docco-husky -name "My Project" app.js lib public

# with wildcards
./node_modules/.bin/docco-husky -name "My Project" *.js lib public

# with global install
docco-husky -name "My Project" *.js lib public

Other Markdown Content

docco-huskycan also include other markdown content from your project. It expects the markdown files to be in a specified directory configured with content_dir. It walks the directory recursively and puts the resulting files in your the output_dirroot including a relative subdirectory.

You can manually link to these files from your README.md or optionally if there is a content_index.mdfile in your content_dirdirectory, this will be injected into the package.json section of the main page just below the module name and description in index.html. This is a convenient way to reference any additional documents in your index.htmlthat you don't want in your README.md file. One reason you may not want links in your README.md file is that these relative links will not resolve when Github renders your project's README.md file.

Output

docco-husky will write generated files to ./docs by default or to the directory specified in the package.json config as output_dir

For all source files, the output will be like

<base>.<ext> (e.g. foo.js) --> <base>.html (e.g. foo.html).

An index.html will be generated and will include a formatted version of a README.md if your project includes it, some details from the a package.json file, and project stats generated by cloc.

Single line comments will only be parsed with the exception os Javascript (as of 0.2.0) which is in an early experimental state.

Repository

https://github.com/mbrevoort/docco-husky


上一篇:gravatar
下一篇:psd
相关教程
关注微信

扫码加入 JavaScript 社区

相关文章

首次访问,需要验证
微信扫码,关注即可
(仅需验证一次)

欢迎加入 JavaScript 社区

号内回复关键字:

回到顶部