The missing documentation tool for your Angular application
Demo : documentation generated for TodoMVC Angular Compodoc demo project
-
Clean, simple design — With Compodoc, the main endpoints are on the left side of your documentation, and all the content on the right side
-
Beautiful themes — 7 themes are available from famous documentation tools like Gitbook, Read the Docs or projects like Vagrant, Laravel, Postmark and Stripe.
-
Search — Compodoc include a powerful search engine (lunr.js) for easily finding your information
-
Automatic table of contents - API table of contents is generated using elements found during files parsing
-
Open-source and on npm - Use it directly in your project using npm and one script, that's it !
-
A local tool - No server needed, no sources uploaded online
-
JSDoc light support - Support of @param, @returns, @link and @example tags
-
Documentation coverage - Get the documentation coverage report of your project
-
Angular-CLI friendly - Compodoc support out of the box Angular-CLI projects
- Screenshots
- Who's using Compodoc ?
- Node.js versions
- Angular-CLI
- Getting Started with compodoc
- Themes
- Common use cases
- Remark for comments
- Remark for routes
- Additional documentation
- Syntax highlighting in markdown files
- Excluding files
- Roadmap
- Extensions
- Contributing
- Contributors
- Resources
- License
Using SoundCloud API client / Angular2 project and default theme (gitbook)
| README page | Overview page |
|---|---|
 |  |
| Modules page | Single module page |
 |  |
| Component page | Source code tab |
 |  |
| Search page | Coverage report |
 |  |
These are some that we know of. Want your project listed here ? Drop us a line.
Compodoc is tested with only LTS versions : v6.9.4 & v4.7.1
Compodoc supports last Angular-CLI version : 1.0.0-rc.0
Just run Compodoc in a fresh or existing project.
Install from npm :
npm install -g compodoc npm install --save-dev compodoc Define a script task for it in your package.json :
"scripts": { "compodoc": "./node_modules/.bin/compodoc -p src/tsconfig.json" } and run it like a normal npm script :
npm run compodoc $ compodoc --help Usage: compodoc <src> [options] Options: -h, --help output usage information -V, --version output the version number -p, --tsconfig [config] A tsconfig.json file -d, --output [folder] Where to store the generated documentation -y, --extTheme [file] External styling theme -n, --name [name] Title documentation -a, --assetsFolder [folder] External assets folder to copy in generated documentation folder -o, --open Open the generated documentation -t, --silent In silent mode, log messages aren't logged in the console -s, --serve Serve generated documentation (default http://localhost:8080/) -r, --port [port] Change default serving port -w, --watch Watch source files after serve and force documentation rebuild --theme [theme] Choose one of available themes, default is 'gitbook' (laravel, original, postmark, readthedocs, stripe, vagrant) --hideGenerator Do not print the Compodoc link at the bottom of the page --toggleMenuItems <items> Close by default items in the menu ( example: 'all' or 'modules','components' ) --includes [path] Path of external markdown files to include --includesName [name] Name of item menu of externals markdown files (default "Additional documentation") --disableSourceCode Do not add source code tab --disableGraph Disable rendering of the dependency graph --disableCoverage Do not add the documentation coverage report --disablePrivateOrInternalSupport Do not show private or @internal in generated documentation | Default (gitbook) | Laravel |
|---|---|
 |  |
| Readthedocs | Stripe |
 |  |
| Vagrant | Postmark |
 |  |
| Original | |
 |
Documentation is generated in default output folder, then run your HTTP server in that folder.
compodoc -p src/tsconfig.json compodoc src -p src/tsconfig.json Documentation was generated in default output folder or a specific one, the local HTTP server is launched at http://localhost:8080
compodoc -s or compodoc -s -d ./doc Documentation is generated in default output folder, and a local HTTP server is available at http://localhost:8080
compodoc -p src/tsconfig.json -s compodoc -p src/tsconfig.json -y your_theme_styles/ Inside your folder you need to provide at least a style.css file with these 5 imports as below.
@import "./reset.css"; @import "./bootstrap.min.css"; @import "./bootstrap-card.css"; @import "./font-awesome.min.css"; @import "./compodoc.css"; Compodoc use bootstrap 3.3.7. You can customize Compodoc easily.
bootswatch.com can be a good starting point. If you want to override the default theme, just provide a bootstrap.min.css file, and it will override the default one.
└── your_theme_styles/ ├── style.css // the main css file with default imports └── bootstrap.min.css // your bootstrap theme A comment description in xxx.component.ts file, between JSDoc comments can be a little short.
Compodoc search for a default README.md file inside the root folder of each component, and add it inside a tab in the component page.
└── my-component/ ├── my.component.ts ├── my.component.spec.ts ├── my.component.scss|css ├── my.component.html └── README.md The live demo as a component documented in that way : TodoMVC Angular Compodoc demo / todo component
Compodoc use Typescript AST parser and it's internal APIs, so the comments have to be JSDoc comments :
/** * Supported comment */ These ones are not supported :
/* * unsupported comment */ /* unsupported comment */ // unsupported comment Currently Compodoc only support these JSDoc tags :
-
@returns -
@param <param name>
/** * @param {string} target The target to process see {@link Todo} * * @example * This is a good example * processTarget('yo') * * @returns The processed target number */ function processTarget(target:string):number; @link: you can use these three syntax like JSDoc:
//for an internal reference {@link Todo} [Todo]{@link Todo} {@link Todo|TodoClass} //for an external link [Google]{@link http://www.google.com} {@link http://www.apple.com|Apple} {@link https://github.com GitHub} @example: for giving an example on directives, components and pipes decorators, use @example or markdown :
/** * Shows all events on a given day. Example usage: * * ``` * <mwl-calendar-day-view * [viewDate]="viewDate" * [events]="events"> * </mwl-calendar-day-view> * ``` */ /** * Shows all events on a given day. Example usage: * * @example * <mwl-calendar-day-view * [viewDate]="viewDate" * [events]="events">; * </mwl-calendar-day-view> */ Follow the style guide, provide a const of type 'Routes' and with an unique name :
const APP_ROUTES: Routes = [ { path: 'about', component: AboutComponent }, { path: '', component: HomeComponent} ]; ... RouterModule.forRoot(APP_ROUTES) Compodoc support the addition of external markdown files for extending the code comments of your application and the main README file.
Create a folder containing markdown files and use --includes flag to extend the documentation. Your folder should contain a summary.json file explaining the structure and files :
summary.json [ { "title": "A TITLE", "file": "a-file.md" }, { "title": "A TITLE", "file": "a-file.md", "children": [ { "title": "A TITLE", "file": "a-sub-folder/a-file.md" } ] } ] Links are supported like regular markdown links.
Compodoc use Marked for markdown parsing and compiling to html. prismjs.js has been added for supporting syntax highlighting.
Just use a normal code block in your markdown with correct language : Github help
The integrated languages are : json, bash, javascript, markdown, html, typescript
For excluding files from the documentation, simply use the exports property of tsconfig.json file.
- study ngast for replacing internal parser
- support for Angular 1.5+ projects written in Typescript
- handle external markdown files as "functional" documentation
- documentation coverage
- routes
- classes
- module(s) page(s) with comments
- component(s) page(s) with comments, API, class
- directives
- injectables
- interfaces
- pipes
There is a plugin available to run Compodoc with Gulp. You can find it on NPM:
https://www.npmjs.com/package/gulp-compodoc
There is a JHipster module available to run Compodoc with JHipster. You can find it on NPM:
https://www.npmjs.com/package/generator-jhipster-compodoc
Want to file a bug, contribute some code, or improve documentation? Excellent !
Read up on our guidelines for contributing.
Inspired by stuff from angular2-dependencies-graph, ng-bootstrap
Logo designed using Book vector designed by Freepik
Everything in this repo is MIT License unless otherwise specified.
MIT © 2016-2017 - Vincent Ogloblinsky