compodoc/compodoc

:notebook_with_decorative_cover: The missing documentation tool for your Angular, Nest & Stencil application

The missing documentation tool for your Angular application.

Live Demo

A live demo is available — see it in action !

The demo features documentation generated for a simple TodoMVC application.

Features

• Clean, simple design — Navigate the documentation on the left side, read it on the right.

• Beautiful themes — Seven themes are available from well known documentation tools like Gitbook, Read the Docs and projects like Vagrant, Laravel, Postmark and Stripe.

• Search — Includes a powerful search engine (lunr.js) for easily finding what you're looking for.

• Automatic table of contents — API table of contents is generated using elements found during files parsing.

• JSDoc light support — Support for @param, @returns, @link, @ignore and @example tags.

• Documentation coverage — Get the documentation coverage report of your project.

• Angular CLI-friendly — Supports Angular CLI projects out-of-the-box.

• Offline — No server needed, no sources uploaded online, documentation generated entirely offline.

• Open-source and on npm — Use it directly in your project using npm and a single script—that's it!

Documentation

Official documentation has moved to https://compodoc.github.io/website/.

Installation

Ready to get started? Read installation instructions.

🏅 Backers

Thank you to all our backers ! Support us with a monthly donation and help us continue our activities. Become a backer

🎖 Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Become a sponsor

Contributing

Want to file a bug, contribute some code, or improve documentation? Excellent!

Read up on our guidelines for contributing.

Contributors

This project exists thanks to all these people.

vogloblinsky	manekinekko	mattlewis92	JonasMH	rprotsyk	daniele-zurico	profimedica

dp-1a	ValentinGot	Blake Simmon	Brigitte Hofmeister	lichangfeng	guilhermevrs

Big Thanks

Cross-browser Testing Platform and Open Source <3 Provided by Sauce Labs

License

Everything in this repository is licensed under the MIT License unless otherwise specified.

Copyright (c) 2016 – 2019 Vincent Ogloblinsky

compodoc's Issues

[BUG] : Routes parsing error when use "System.import('')"

import { Routes, RouterModule }  from '@angular/router';
import { Layout } from './layout.component';
const routes: Routes = [
  { 
    path: '', component: Layout, children: [
      { path: '', redirectTo: 'home', pathMatch: 'full' },
      { path: 'home', loadChildren: () => System.import('../home/home.module') }
    ]
  }
];

export const ROUTES = RouterModule.forChild(routes);

Error: listen EACCES 0.0.0.0:8080

I'm trying to see the documentation but when the "compodoc" it is serving the site it returns this message "Error: listen EACCES 0.0.0.0:8080".

I'm using:

angular-cli: 1.0.0-beta.17
NPM 3.10.7
Node 6.5.0

When I run: compodoc -p src/tsconfig.json -s I receive this message
[16:58:01] Documentation generated in ./documentation/ in 64.032 seconds
[16:58:01] Serving documentation from ./documentation/ at http://127.0.0.1:8080
Error: listen EACCES 0.0.0.0:8080

When I run: compodoc -s I receive this message
[07:10:36] Serving documentation from ./documentation/ at http://127.0.0.1:8080
Error: listen EACCES 0.0.0.0:8080

Thanks,

bug: marked ignore syntax highlighting

when in the readme file you try to specify the language to use it's ignored.
example:
html
should produce something like that:

<h1>
  <a name="heading-" class="anchor" href="#heading-">
    <span class="header-link"></span>
  </a>
  heading+
</h1>

instead it produce:

<h1>
  <a name="heading-" class="anchor" href="#heading-">
    <span class="header-link"></span>
  </a>
  heading+
</h1>

reference: https://github.com/chjj/marked#highlight

fix(mobile) design

The right is not visible on mobile.

[BUG] Syntax highlighting stops after unsupported comment (//)

Overview of the issue

Syntax highlighting stops after unsupported comment by compodoc like this:

Operating System, Node.js, npm, compodoc version(s)

Windows 7
node: 6.9.2
npm: 4.0.5
compodoc: 0.0.28

Angular configuration, a package.json file in the root folder

"angular-cli": {},
"scripts": {
"start": "ng serve --proxy-config proxy.conf.json",
"lint": "tslint "src/**/*.ts"",
"test": "ng test",
"pree2e": "webdriver-manager update --standalone false --gecko false",
"e2e": "protractor",
"compodoc": "./node_modules/.bin/compodoc -h stripe -p src/tsconfig.json"
},
"private": true,
"dependencies": {
"@angular/common": "~2.4.1",
"@angular/compiler": "~2.4.1",
"@angular/core": "~2.4.1",
"@angular/forms": "~2.4.1",
"@angular/http": "~2.4.1",
"@angular/platform-browser": "~2.4.1",
"@angular/platform-browser-dynamic": "~2.4.1",
"@angular/router": "~3.4.1",
"@webcomponents/custom-elements": "1.0.0-alpha.3",
"clarity-angular": "^0.8.0",
"clarity-icons": "^0.8.0",
"clarity-ui": "^0.8.0",
"core-js": "^2.4.1",
"lodash": "^4.17.4",
"mutationobserver-shim": "^0.3.2",
"rxjs": "5.0.2",
"ts-helpers": "^1.1.2",
"zone.js": "^0.7.4"
},
"devDependencies": {
"@types/jasmine": "^2.5.40",
"@types/lodash": "^4.14.45",
"@types/node": "^6.0.57",
"angular-cli": "1.0.0-beta.24",
"codelyzer": "2.0.0-beta.4",
"compodoc": "0.0.28",
"jasmine-core": "2.5.2",
"jasmine-spec-reporter": "^3.0.0",
"karma": "1.3.0",
"karma-chrome-launcher": "^2.0.0",
"karma-cli": "^1.0.1",
"karma-jasmine": "^1.1.0",
"karma-remap-istanbul": "^0.4.0",
"protractor": "~4.0.14",
"ts-node": "~2.0.0",
"tslint": "4.2.0",
"typescript": "~2.0.10"
}

Compodoc installed globally or locally ?

locally as seen in the package.json above.

Motivation for or Use Case

Reproduce the error

I believe you can reproduce this issue by commenting with // on any line of your TS code.

Related issues

Suggest a Fix

[FEATURE] : generate json only

Please add an option to create only json with documentaion

[FEATURE] : Is there any way to have documentation working without any server

A way to work document without any server

We have some use cases where we need to give documentation to our Vendor(Client) in some hard drive. I have tried this documentation its look super cool and I can see it can be generated locally in the folder. But this documentation needs a web server to display documentation. In our case, We need to have that works from anywhere in a physical folder. Double click via index.html from the physical folder. I was just wondering is there a way to generate that documentation that will work without the web server.

using todo mvc generating doc

Hi,
I checkout the project mvc and trying to run it on my side:

./node_modules/.bin/compodoc -f src/tsconfig.json -d doc

the generation process complete successfull running this command:

./node_modules/.bin/compodoc -f src/tsconfig.json -d doc

but when I try to run:

Danieles-MacBook-Pro-2:compodoc-demo-todomvc-angular2-master danielezurico$ compodoc -s
[11:22:49] Serving documentation at http://127.0.0.1:8080
[11:22:49] Entry file was not found

what I missed?

In the script n[m run doc there's that one:
-b https://compodoc.github.io/compodoc-demo-todomvc-angular2/
but no idea what it should be

[BUG] : Base option not working when relative

compodoc -p src\tsconfig.json -b .

My use case is to be able to navigate the site without serving it, just opening the index.html.
Setting the base option to . or "" works but only for the main pages. It fails on module pages for example.

logo is overlaying menu

example project: https://github.com/c1rus/event-view

feat(app): search bar

Unhandled promise rejection on generation

Trying to generate a demo project documentation. It fails in the final step

[19:14:41] Searching package.json file [19:14:41] package.json file found [19:14:41] Searching README.md file [19:14:41] README.md file found [19:14:41] Get dependencies data (node:9818) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): RangeError: Invalid array length
Calling it local on the project root via

node_modules/.bin/compodoc -p tsconfig.json -d ./docs

Btw. Respect, really nice tool and idea behind it :)

[BUG] : Error during graph generation

Error during graph generation: : /bin/sh: /usr/local/lib/node_modules/.bin/ngd: No such file or directory

I just did npm i -g compodoc && compodoc -p src/tsconfig.json -s

I can't seem to figure out what ngd is about.

I can serve the documentation (it's really nice! ), only thing is that is says "your browser does not support svg", which it does, so it might be related.

documentation folder not generated

Hello, I have installed compodoc, and ran the command to generate the docs. it looks like it is working but no documentation folder is generated.

multiple class declarations in one file

Hi, after upgrading from version 0.0.19 to 0.0.22, im unable to have multiple class declarations in one file. Im getting this error:

UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): RangeEr
ror: Invalid array length
DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise
rejections that are not handled will terminate the Node.js process with a non-zero exit code.

example:

import { Component } from '@angular/core';

class Car {
    speed: number;
}

/**
 * The main component
 */
@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {

}

module dependencies graphs not generated

The overview graph is generated, but module section looks like below. I dont see any error, when docs are generating.

example project: https://github.com/c1rus/event-view

missing some generated pages

after upgrading from .17 to .18, the build completes without warnings or errors and I am missing a bunch of the pages at the root level that were previously generated in .17. The following html files aren't generated anymore and overview.html does not create links for these files either:

components.html
directives.html
injectables.html
pipes.html
classes.html

pages for individual components are still generated and overview.html is still generated

[FEATURE] : split in multiple modules

1st pass:

• publish in npm scoped module

2nd pass :

• use @compodoc/ngd-core for parsing files

• use @compodoc/ngd-generator for generating graph with context : static (svg) or web (d3js)

Design doc here: https://docs.google.com/document/d/1BdlLdAvQkedI_14ZB7HeMMAQc1WWqOQ4ZLHqSpeKG7A/edit?ts=5846b3ef

fix(module): exclude Angular2 modules

Exclude HttpModule, FormsModule etc from module imports list

[FEATURE] : Support routing module and lazy routes

Hey,
first of all, thanks for your amazing job !
Would it be possible to add support for routing modules and lazy loaded routes ?
It seems that only inlined routes are supported for now

Error when semi-colon after class function

I get an error RangeError: Invalid array length when there is a semi-colon after a class function.

e.g.

@Component({...})
export class SomeComponent {
  testFunction(): void {
  };
}

It's not really a problem to delete the extraneous semi-colons, but the error message could be a little more helpful. It took me a while to find the problem.

[FEATURE] Source folder option

Overview of the issue

Seems strange to me that there is no option to specify where my source files are. Currently it scans all .ts file in my root folder, so with the following structure I get my examples folder scanned even if I don't wish it.

/
--examples
--src

Suggest a Fix

My current script is compodoc ./src -p tsconfig.json -d doc -s and I think it sounds reasonable to pass the source folder this way.

P.S. Great work anyway, very promising!

[BUG] : graph generation error with spaces in folder path

Overview of the issue

if the project path contains spaces, the graph generation breaks with this stacktrace:

Error during graph generation: : 'C:\Users\IEUser\Documents\www\tests-compodoc\test' is not recognized as an internal or external command,
operable program or batch file.

Operating System, Node.js, npm Version(s)

Windows 7, node.js 7.0.0, npm 3.10.8

Compodoc installed globally or locally ?

compodoc locally

Reproduce the error

npm run doc

Not all routes being scanned

Hi,

I have angular-cli app with few lazy loaded modules.

After generating documentation there are only listed routes from first submodule.
But I have one main routing module and 3 submodules.

You can see my routing modules here: https://github.com/shardis/shardis/search?utf8=%E2%9C%93&q=RouterModule.for&type=Code

Only first AboutRoutingModule was scanned and listed in docs

[BUG] : Dependencies.svg file not generated

I am currently running into an issue where the graph/dependencies.svg file does not appear to be generated. I have performed the following steps:

1. Installed via "npm install --save-dev compodoc".
2. Build and run via an npm script:
   "compodoc": "./node_modules/.bin/compodoc -p tsconfig.json -s --port 8081"
3. An error is displayed where the graph should be, stating that "Your browser does not support SVG".
4. I manually installed the angular2-dependencies-graph in dev dependencies, this did not help.
5. The following errors are displayed in the developer console of Google Chrome while sitting on the overview page.

menu.js:31 Uncaught TypeError: Cannot read property 'offsetTop' of null

svg-pan-zoom.controls.js:1 GET http://127.0.0.1:8081/graph/dependencies.svg 404 (Not Found)

svg-pan-zoom.min.js:161 Uncaught TypeError: this.options.svg.createSVGMatrix is not a function

It is worth noting that I do not have a README.md file, thus that is skipped during the building of the documents. However, that is the only error I receive during build.

[BUG] Routes Parsing Error with path defined in const.

Overview of the issue

I have app level config file for const as seen in this commit
https://github.com/chunghha/clarity-seed/commit/006663f8e5bef23c71844036ad7255ff83796ab2

if I use the APP_CONFIG in the routes, compodoc throws this error while parsing.
"Routes parsing error, maybe a trailing comma ?"

Operating System, Node.js, npm, compodoc version(s)

Linux(ubuntu16.04)
node: 7.3.0
npm: 3.10.10

Angular configuration, a package.json file in the root folder

please see the package.json in the repository.

Compodoc installed globally or locally ?

locally.

Motivation for or Use Case

The Routes is parsed without error if I don't use APP_CONFIG ( as good one with master branch, https://chunghha.github.io/clarity-seed/routes.html ) and nothing wrong to use the APP_CONFIG for the app to run. Thus, compodoc should parse the Routes without this error.

Reproduce the error

please check out the compodoc branch to reproduce this error.

Related issues

Suggest a Fix

Suggestion - source code

A good idea could be add a third tab to see the source code of the module or component.

[BUG] : map generated too small in height

First of all I'm super excited about that tool really awesome job!.
Now the problem:

I think that is better if we reduce the height of the box and we give more height to the map/chart generated

[ROADMAP] v1.0.0

• handle external markdown files as "functional" documentation.
  A starting work is located on feature branch "ext-md"

• watch/recompile feature while serving documentation.
  A starting work is located on feature branch "watch-flag".
  The issue located here : #20

• rewrite routes page.
  A starting work is located on feature branch "router-tree-diagram".
  The issue located here : #17

• others TODOS in related project : https://github.com/compodoc/compodoc/projects/2

Error on Global Installation - Unexpected Token

Hello,

I´ve installed the compodoc globally but I´m having issue on Windows 10. Please check the error below:

Bug: double forward slash causes graph generation error

Should double forward slashes be treated as a single line comment?

I believe this causes a previously referenced graph error.

ngd

Hello everyone I'm trying to use the tool but when he has almost finished it throw this error:

[10:39:49] Process main graph
[10:39:49] Error during graph generation: : /bin/sh: /Users/danielezurico/Documents/blackswan/explore-workspace/nest-lib-dashboard-charts/node_modules/.bin/ngd: No such file or directory

what is missed?

handlebars is not in the dependency list

After npm install I get this:

Error: Cannot find module 'handlebars'
    at Function.Module._resolveFilename (module.js:469:15)
    at Function.Module._load (module.js:417:25)
    at Module.require (module.js:497:17)
    at require (internal/module.js:20:19)
    at Object.<anonymous> (/usr/local/lib/node_modules/compodoc/dist/index.js:8:18)
    at Module._compile (module.js:570:32)
    at Object.Module._extensions..js (module.js:579:10)
    at Module.load (module.js:487:32)
    at tryModuleLoad (module.js:446:12)
    at Function.Module._load (module.js:438:3)

had to npm install -g handlebars to get it working...

A few feature requests

Just a few "nice to have" feature requests:

• Properties defined in constructor setters (e.g. constructor(public someClass)) are not currently included in the properties lists.
• An Interfaces section, similar to Classes section except listing any TS interfaces. Currently, interfaces don't seem to be included anywhere in the doc output.
• If the type for a property or parameter references a type that is available elsewhere in the docs, turn the type into a hyperlink to the documentation on that type. (Basically, types link to the docs on that type if they are available.)
  • Extra type linking bonus: if a type references an Angular type, link to the Angular API docs for that type?

As always, thanks for the very helpful tool!

bug: node 7?

Hi! I'm wondering what features in node 7 breaks compodoc? Noticed it when I tried out angular-seed.

error [email protected]: The engine "node" is incompatible with this module. Expected version ">= 5.4.1 < 7".
error Found incompatible module

[FEATURE] : display properties/IO in rows

is it better ?

http://www.material-ui.com/#/components/auto-complete

fix(dependencies): handle multiple statements in the same file

• multiple declarations : component, interface, class, etc

fix(app): left menu | scrollToItem

scroll to active link in the menu

[BUG] : wont serve or open generated documentation

I have tested multiple configurations on multiple machines and I can not seem to get the project to serve the documentation. Either with the default settings or by specifying a port address. Also it does not seem to open generated documentation with --open

Overview of the issue

Operating System, Node.js, npm Version(s)

On windows 7 and mac, Installed with npm v4.0.5 & node v6.9.1

Angular configuration, a package.json file in the root folder

./node_modules/.bin/compodoc --theme stripe --name LogistiCAD-TNG-UI --tsconfig ./tsconfig.json --serve --port 2200 --open --hideGenerator

Compodoc installed globally or locally ?

both

feat(app): link external markdown in the main one

I've the following structure in my code:

• README.md

src
  component
     component.html
     compontent.ts
     component.scss
    component.spec
    README.md

Now I would to point the attention on the README inside the subfolder. It explain exactly what the component does and all the properties that it use. There's any way to display it as well?

I know that is not easy but could be a workaround if I link them in the main readme.md?
Open for suggestions

bug: Are JSDoc comments required to generate doc entries?

It appears that doc entries for properties and methods are only created if a code element has a JSDoc comment on it. Is that right, and if so, is that deliberate? I haven't looked into how the app code is parsed, but if the TS compiler is used then it seems like that would supply sufficient information to create prop/method entries with name, params, types, etc. Everything beyond an actual text description.

Thoughts?

And thanks for the work on this. Something like this was sorely needed!

[BUG] : passing declarations as array

passing declarations as array generates this.

and when i click on 'routedComponents', i get:

example project: https://github.com/c1rus/event-view

styling theme

Is possible to have a different style? Like generate a theme or a css or something like that?

Comment Format

First off, excellent plugin! I've used plenty of javascript documentation generators and this has been the absolute easiest to get working out-of-the-box.

I think the docs could use some clarification about how to format code comments so compodoc can parse them. Or modifications should be made to the plugin to handle different comment formats. For example, in my angular cli project...

/**
 This comment seems to be parsed
*/
@Component(...

/*
 While this one (the WebStorm default block comment with only one *) does not.
*/
@Component(...

// Also, this one doesn't get parsed, either
@Component(...

[FEATURE] : add a watch flag

Watch during time src files while serving documentation.

If one file change, just render the html page, live-server will reload after.

[FEATURE] : migrate routes page to d3.js

These examples are good starting-points :

• http://mbostock.github.io/d3/talk/20111018/tree.html
• http://charts.animateddata.co.uk/datavistree/
• https://github.com/d3/d3-hierarchy/blob/master/README.md#tree
• http://www.d3noob.org/2014/01/tree-diagrams-in-d3js_11.html

[BUG] Syntax highlighting issue with tabs

Overview of the issue

Tabs are not correctly handled

    constructor(todoStore: TodoStore) {
		this.todoStore = todoStore;
	}

    addTodo() {
		if (this.newTodoText.trim().length) {
            this.todoStore.add(this.newTodoText);
			this.newTodoText = '';
		}
	}

Routes parsing error, maybe a trailing comma ?

I do not have trailing comma in my routes definition. However, I still get this error and my documentation doesn't generate.

Honestly, I don't even care if my routes are documented. It would be nice if this wouldn't fail the entire documentation generation process because of one syntax error. Seems like a pretty common problem with these documentation generators.

feat(app): add Node.js / Gulp option

Provide an access with Node.js

const compodoc = require('compodoc')

and with gulp ?

const compodoc = require('gulp-compodoc')

[FEATURE] : Version selector

It would be great if there was an option to generate the documentation for a specific version of the project.
Then there could be a select box to switch between the different versions. See here for an example.