Skip to content

Latest commit

 

History

History
145 lines (102 loc) · 4.64 KB

tips-and-tricks.md

File metadata and controls

145 lines (102 loc) · 4.64 KB

Table of Contents

Styling the documentation

compodoc -p tsconfig.doc.json -y your_theme_styles/

Inside your folder you need to provide at least a style.css file with these 7 imports as below.

@import "./reset.css";
@import "./bootstrap.min.css";
@import "./bootstrap-card.css";
@import "./prism.css";
@import "./ionicons.min.css";
@import "./compodoc.css";
@import "./tablesort.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, module, directives etc

A comment description in xxx.component.ts file, between JSDoc comments can be a little short.

Compodoc search for a default xxx.component.md file inside the root folder of each component, and add it inside a tab in the component page. It is the same for class, module etc.

└── my-component/
    ├── my.component.ts
    ├── my.component.spec.ts
    ├── my.component.scss|css
    ├── my.component.html
    └── my.component.md

Additional documentation

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.

Documentation of several apps in a monorepository

Nx is an open source, smart, fast and extensible build system. It follows an approach where potentially multiple apps and libs can live in the same workspace (aka "monorepo").

A monorepository with multiple apps could easily be documentated by Compodoc. You just have to run Compodoc in each apps seperately. Here is an example with nx-examples :

.
├── apps
│   ├── demo
│   │   └── src
│   │       └── tsconfig.doc.json
│   ├── profile
│   ├── school
│   └── teach
└── README.md

Just run Compodoc like that :

cd apps/demo/src
compodoc -p tsconfig.doc.json -s

// or

compodoc -p apps/demo/src/tsconfig.doc.json -s

Syntax highlighting in markdown files

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

Excluding files

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

You can exclude specific file with name app/myfile.ts or with glob pattern **/*.spec.ts.

Including files

For including files from the documentation, simply use the include property of tsconfig.json file.

You can include specific file with name app/myfile.ts or with glob pattern **/*.ts.