Compodoc: The missing documentation tool for your Angular application

The missing documentation tool for your Angular application

Compodoc: The missing documentation tool for your Angular application

#Features ------------ * **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](https://www.gitbook.com), [Read the Docs](https://readthedocs.org/) or projects like [Vagrant](https://www.vagrantup.com/docs/), [Laravel](https://laravel.com/docs/5.3), [Postmark](http://developer.postmarkapp.com/) and [Stripe](https://stripe.com/docs/api). * **Search** — Compodoc include a powerful search engine ([lunr.js](http://lunrjs.com/)) 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 # Live Demo [Demo](https://compodoc.github.io/compodoc-demo-todomvc-angular/) : documentation generated for [TodoMVC Angular Compodoc demo project](https://github.com/compodoc/compodoc-demo-todomvc-angular) # Static Demo Using [SoundCloud API client / Angular2 project](https://github.com/r-park/soundcloud-ngrx) and default theme (gitbook) README page | Overview page :-------------------------:|:-------------------------: ![screenshot-1](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/1.png) | ![screenshot-2](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/2.png) Modules page | Single module page ![screenshot-3](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/3.png) | ![screenshot-4](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/4.png) Component page | Source code tab ![screenshot-5](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/5.png) | ![screenshot-6](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/7.png) Search page | Coverage report ![screenshot-7](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/6.png) |![screenshot-8](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/8.png) # Why this tool ? Because we doesn't find our needs on existing tools. We want to have a single place where there is : - api documentation of code - component(s), directive(s), pipe(s), ... documentation - general documentation (\*.md files) # Why not a SPA for outputed documentation ? [KISS principle](https://en.wikipedia.org/wiki/KISS_principle) or shortly __"Keep it simple"__. We think static html files are simpler than another SPA inside an "SPA documentation". # Who's using Compodoc ? - [angular-seed](https://github.com/mgechev/angular-seed) - [angular-calendar](https://github.com/mattlewis92/angular-calendar) These are some that [we know of](https://github.com/search?q=compodoc+filename%3Apackage.json+-user%3Acompodoc&ref=searchresults&type=Code&utf8=%E2%9C%93). Want your project listed here ? Drop us a line. # Table of Contents - [Node.js versions](#node.js-versions) - [Angular-CLI](#angular-cli) - [Getting Started with compodoc](#getting-started-with-compodoc) - [Install](#install) - [Usage](#usage) - [Local installation](#local-installation) - [Themes](#themes) - [Common use cases](#common-use-cases) - [Render documentation](#render-documentation) - [Serve generated documentation with compodoc](#serve-generated-documentation-with-compodoc) - [Render documentation, and serve it with compodoc](#render-documentation-and-serve-it-with-compodoc) - [Styling the documentation](#styling-hte-documentation) - [Documentation of each component](#documentation-of-each-component) - [Syntax highlighting in markdown files](#syntax-highlighting-in-markdown-files) - [Excluding files](#excluding-files) - [Remark for comments](#remark-for-comments) - [Remark for routes](#remark-for-routes) - [Roadmap](#roadmap) - [Extensions](#extensions) - [Contributing](#contributing) - [Contributors](#contributors) - [Resources](#resources) - [License](#license) ## Node.js versions Compodoc is tested with only LTS versions : v6.9.4 & v4.7.1 ## Angular-CLI Compodoc supports last Angular-CLI version : [1.0.0-beta-26](https://github.com/angular/angular-cli/blob/master/CHANGELOG.md#100-beta26-2017-01-19) Just run Compodoc in a fresh or existing project. ## Getting Started with compodoc ### Install Install from npm : ``` npm install -g compodoc ``` ### Usage ``` $ compodoc --help Usage: compodoc [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 --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 --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 ``` ### Local installation ``` 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 ``` ## Themes Default (gitbook) | Laravel :-------------------------:|:-------------------------: ![theme-gitbook](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/theme-gitbook.png) | ![theme-laravel](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/theme-laravel.png) Readthedocs | Stripe ![theme-readthedocs](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/theme-readthedocs.png) | ![theme-stripe](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/theme-stripe.png) Vagrant | Postmark ![theme-vagrant](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/theme-vagrant.png) | ![theme-postmark](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/theme-postmark.png) Original | ![theme-original](https://raw.githubusercontent.com/compodoc/compodoc/master/screenshots/theme-original.png) | ## Common use cases ### Render documentation Documentation is generated in default output folder, then run your HTTP server in that folder. ``` compodoc -p src/tsconfig.json ``` ### Render documentation while providing source folder ``` compodoc src -p src/tsconfig.json ``` ### Serve generated documentation with compodoc Documentation was generated in default output folder or a specific one, the local HTTP server is launched at [http://localhost:8080](http://localhost:8080) ``` compodoc -s or compodoc -s -d ./doc ``` ### Render documentation, and serve it with compodoc Documentation is generated in default output folder, and a local HTTP server is available at [http://localhost:8080](http://localhost:8080) ``` compodoc -p src/tsconfig.json -s ``` ### Styling the documentation ``` 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](http://getbootstrap.com/) 3.3.7. You can customize Compodoc easily. [bootswatch.com](http://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 ``` ### Documentation of each component 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](https://compodoc.github.io/compodoc-demo-todomvc-angular/components/TodoComponent.html) ## Remark for comments 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 : - ```@param ``` - ```@returns``` - ```@example``` - ```@link``` ``` /** * @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; ``` For @link you can use this 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} ``` 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 * ; * */ ``` ## Remark for routes Follow the style guide and provide a const of type 'Routes' : ``` const APP_ROUTES: Routes = [ { path: 'about', component: AboutComponent }, { path: '', component: HomeComponent} ]; ... RouterModule.forRoot(APP_ROUTES) ``` ### Syntax highlighting in markdown files Compodoc use [Marked](https://github.com/chjj/marked) for markdown parsing and compiling to html. [highlight.js](highlightjs.org) has been added for supporting syntax highlighting. Just use a normal code block in your markdown with correct language : [Github help](https://help.github.com/articles/creating-and-highlighting-code-blocks/) The integrated languages are : __json, bash, javascript, markdown, html, typescript__ ### Excluding files For excluding files from the documentation, simply use the __exports__ property of [__tsconfig.json__](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file. ## Roadmap - [ ] handle external markdown files as "functional" documentation - [ ] watch/recompile feature while serving documentation - [ ] support for Angular 1.5+ projects written in Typescript - [x] documentation coverage - [x] routes - [x] classes - [x] module(s) page(s) with comments - [x] component(s) page(s) with comments, API, class - [x] directives - [x] injectables - [x] interfaces - [x] pipes ## Extensions ### Gulp There is a plugin available to run Compodoc with Gulp. You can find it on NPM:
[https://www.npmjs.com/package/gulp-compodoc](https://www.npmjs.com/package/gulp-compodoc) ### JHispter 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](https://www.npmjs.com/package/generator-jhipster-compodoc) ## Contributing Want to file a bug, contribute some code, or improve documentation? Excellent ! Read up on our guidelines for [contributing](https://github.com/compodoc/compodoc/blob/master/.github/CONTRIBUTING.md). ## Contributors [

](https://github.com/vogloblinsky) |[

](https://github.com/daniele-zurico)|[

](https://github.com/daniele-zurico)| :---: |:---: |:---: |:---: |:---: |:---: | [vogloblinsky](https://github.com/vogloblinsky) |[daniele-zurico](https://github.com/daniele-zurico)|[mattlewis92](https://github.com/mattlewis92) ## Resources Inspired by stuff from [angular2-dependencies-graph](https://github.com/manekinekko/angular2-dependencies-graph), [ng-bootstrap](https://ng-bootstrap.github.io) Logo designed using [Book vector designed by Freepik](http://www.freepik.com/free-photos-vectors/book) ## License Everything in this repo is MIT License unless otherwise specified. MIT © 2016 - [Vincent Ogloblinsky](http://www.vincentogloblinsky.com)

	Stars	Issues	Version	Updated	Created
compodoc	3,958	98	0.0.41	7 years ago	8 years ago
react-cosmos			6.1.1	2 months ago	8 years ago
storybook	82,975	1,862	8.0.10	9 days ago	8 years ago
tsdoc	47	15	0.0.4	11 years ago	11 years ago
typedoc	7,392	41	0.25.13	a month ago	10 years ago

compodoc vs react-cosmos vs storybook vs tsdoc vs typedoc

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past