This package has been deprecated

    Author message:

    Compodoc has moved to @compodoc/compodoc

    compodoc

    0.0.41 • Public • Published

    Compodoc: The missing documentation tool for your Angular application
    Build Status Build Status Codecov npm badge npm dependencies npm devDependencies MIT badge

    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, 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

    Live Demo

    Demo : documentation generated for TodoMVC Angular Compodoc demo project

    Static Demo

    Using SoundCloud API client / Angular2 project and default theme (gitbook)

    README page Overview page
    screenshot-1 screenshot-2
    Modules page Single module page
    screenshot-3 screenshot-4
    Component page Source code tab
    screenshot-5 screenshot-6
    Search page Coverage report
    screenshot-7 screenshot-8

    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 or shortly "Keep it simple". We think static html files are simpler than another SPA inside an "SPA documentation".

    Who's using Compodoc ?

    These are some that we know of. Want your project listed here ? Drop us a line.

    Table of Contents

    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

    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 <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
      --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 theme-laravel
    Readthedocs Stripe
    theme-readthedocs theme-stripe
    Vagrant Postmark
    theme-vagrant theme-postmark
    Original
    theme-original

    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

    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

    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 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
    

    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

    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 <param name>
    • @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:
     *
     * ```
     * &lt;mwl-calendar-day-view
     *  [viewDate]="viewDate"
     *  [events]="events"&gt;
     * &lt;/mwl-calendar-day-view&gt;
     * ```
     */
    
     /**
      * Shows all events on a given day. Example usage:
      *
      * @example
      * <mwl-calendar-day-view
      *  [viewDate]="viewDate"
      *  [events]="events">;
      * </mwl-calendar-day-view>
      */
    

    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 for markdown parsing and compiling to html. highlight.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

    Excluding files

    For excluding files from the documentation, simply use the exports property of tsconfig.json file.

    Roadmap

    • handle external markdown files as "functional" documentation
    • watch/recompile feature while serving documentation
    • support for Angular 1.5+ projects written in Typescript
    • documentation coverage
    • routes
    • classes
    • module(s) page(s) with comments
    • component(s) page(s) with comments, API, class
    • directives
    • injectables
    • interfaces
    • 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

    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

    Contributing

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

    Read up on our guidelines for contributing.

    Contributors

    vogloblinsky daniele-zurico mattlewis92
    vogloblinsky daniele-zurico mattlewis92

    Resources

    Inspired by stuff from angular2-dependencies-graph, ng-bootstrap

    Logo designed using Book vector designed by Freepik

    License

    Everything in this repo is MIT License unless otherwise specified.

    MIT © 2016 - Vincent Ogloblinsky

    Install

    npm i compodoc

    DownloadsWeekly Downloads

    3,407

    Version

    0.0.41

    License

    MIT

    Last publish

    Collaborators

    • vogloblinsky