Typedoc: Correct usage when having multiple projects?

[asgerjensen]

I am creating a library that consists of several npm packages, but would like to document them as one.

My folder structure looks like this:

     library-src/
           modules/@mycompany/module1/
                  index.ts
                  src/otherfolders/other.ts   
           modules/@mycompany/src/module2/
           modules/@mycompany/src/module3/
           ...
           typedoc.json
           node_modules/
           tsconfig.ts

Each module has an index.ts that exports some classes, each defined in subdirectories.

My tsconfig looks like this:

...
    "baseUrl": ".",
    "paths": { 
    "@mycompany/module1" : ["modules/@mycompany/module1/index.ts"],
    "@mycompany/module2" : ["modules/@mycompany/module2/index.ts"]
    },
  "files": [
    "modules/@mycompany/module1/index.ts",
    "modules/@mycompany/module2/index.ts",
    "modules/@mycompany/module3/index.ts",
    "modules/@mycompany/module4/index.ts",
  ],

my typedoc.json looks like this

{
  "name": "My company module",
  "mode": "modules",
  "out": "doc",
  "theme": "default",
  "ignoreCompilerErrors": "false",
  "preserveConstEnums": "true",
  "excludeExternals": "true",
  "externalPattern": "@angular/*",
  "stripInternal": "false"
}

If i run

node_modules/typedoc/bin/typedoc --options typedoc.json ./modules/

It compiles everything, but creates documentation only for the index.ts files, and it only contains the exported constants, and none of the classes.

If i change tsconfig.json, by removing the files section, and setting the baseUrl to /modules/, and runs the same typedoc command, it generates documentation for every class, but sees them as seperate External Modules, meaning i get hundreds of entries in the initial TOC, with the full filename used as module name. I can use mode=files instead, but it still just leaves everything in a big pile.

What I'd like to end up with a TOC of 4 modules, and when i click on one, it would show the classes in that module.

I played around with the typedoc-plugin-external-module-name, but that requires me to add a preabmble to each and every file, which seems... wrong somehow.

Maybe I'm just not getting what a typescript module is. I was under the impression that if tsrecord.json had it listed in the files section, it was an internal module, so my expectation would be that it would then treat all deps exported from that, as part of that module.

Or maybe I just misunderstand what internal and external means. I thought internal meant : "This is what this module provides", and external meant "this is somehow also included, but who knows why"

Anyways, hope someone will help shedding some light on how best to achieve what i'm trying to do, and can clarify if I should expect my modules to be recognized as internal or external.

[jamietre]

I am also looking for guidance on how to create heirarchical documentation. I followed a similar exploration as OP here. My use case is simpler (I think) - I just have a single package that we publish via a private npm registry, but its exports are structured heirarchically. This is a utility library. There's a single export from the package that exposes "namespaces", e.g.

import * as crypto from "./crypto"
import * as objects from "./objects"
import * as promises from "./promises"
import * as functions from "./functions"
import * as strings from "./strings"
export { crypto, objects, promises, functions, strings }

The default export from each of these areas exposes a handful of member functions. So ideally I'd have these namespaces as the top-level index, and a list of each of methods within each of those five top-levels. Right now I just get a flat list of every export.

I tried using Typescript namespaces but they don't really play well with ES6 exports and re-exporting this way (and as far as I can tell the current best practice is not to use them anyway). Tried a variety of configurations, and ended up with this:

{
    "excludePrivate": true,
    "excludeNotExported": true,
    "excludeExternals": true,
    "moduleResolution": "node",
    "includeDeclarations": false,
    "mode": "file",
    "out": "dist/doc/html"
}

This at least only publishes the exports, and uses the object name instead of the file path in the index, but there's no structure.

I realize there might be no inherently obvious way for typedoc to divine my intentions here, but if there's a way I can reorganize or tag the code either in jsdoc or with typescript, then I'd be quite willing to do so to get better documentation.

[Gerrit0]

In 0.20, this is made significantly easier - Give typedoc your entry points, and it will document each entry point as a separate module. The content of each module will be extracted using the compiler API, so typedoc will document the same exported symbols as a downstream user would see.