Use of TS submodules aren't well rendered

[Vadorequest]

Hello,

First thing first, thanks a lot for that typedoc generator, it is great and I plan on using it for several project.

But we have seen a problem with our nested TS modules, i.e:

module Payline.Spinner {

}

When I do something like that (and that's the way we use to define submodules), it is hard to navigate
inside the documentation, because all sub-levels are on a different page.

Then, on click on "Payline" we get to this page.

So, we basically need to click three times to get to actual class and it makes the navigation difficult.

Would it be possible to have something more like a tree, which would display not only the module name but also all the classes associated to that module? This way we could have an overview of all classes that belong to a module (or submodule) and access any of them directly.

It may be related to #68, but I'm not sure.

Thanks :)

[sebastian-lenz]

Hi, nice to hear from you. The sidebar of the generated documentation contains a list of all modules and the symbols of the current module. However, if your project contains more than 10 modules we only show the top level modules in first place.

Could we solve your problem by allowing you to control this behavior? You can fake change this behavior by setting the threshold in node_modules/typedoc/bin/typdoc.js at line 7906 to a very high value.

[Vadorequest]

Thanks for the reply!

But I don't think that's something to do with the modules number, it's more about nesting modules i guess, I only have one top module here: Payline, which may contain several submodules, but no more than 4 at the time. So I guess making that change won't really help me.

Would you like a docs/ sample to see by yourself if you can't replicate that behaviour?

[sebastian-lenz]

If you have less than 10 modules in total, the sidebar will display submodules as well. The sidebar will list them with their fully qualified names.

[Vadorequest]

I understand, but if you look at that screen you'll see that it is not really user friendly. A view in list or even better, with accordion collapse wouldn't it be better? (overview, navigation, ...)

And even the sidebar doesn't link to the class directly, I need to click 3 times to get to the classe documentation itself:

1. Click on Api (sidebar)
2. Click on Payline (sidebar)
3. Click on Api (center)

I don't know if you understand exactly what I mean, maybe you never ran into that kind of issue (I guess so). :)

[kamranayub]

This makes sense. Sometimes a module won't have any members, especially top
level ones. Maybe a flag to auto-compact empty modules? So it will display
A.B if A is empty. Or maybe something else, since I could see still see
documenting each module level.

I think in the modules section of the sidebar, having the option to display
as a tree is a nice idea with expand/collapse. Could a custom template do
that easily?

Also it might be help this specific case if you could just pass in the
"starting symbol" which would set index.html to the specific symbol.
--startSymbol Payline.Api

On Mon, Apr 13, 2015, 23:26 Vadorequest [email protected] wrote:

I understand, but if you look at that screen you'll see that it is not
really user friendly. A view in list or even better, with accordion
collapse wouldn't it be better? (overview, navigation, ...)

And even the sidebar doesn't link to the class directly, I need to click 3
times to get to the classe documentation itself:

1. Click on Api (sidebar)
2. Click on Payline (sidebar)
3. Click on Api (center)

I don't know if you understand exactly what I mean, maybe you never ran
into that kind of issue (I guess so). :)

—
Reply to this email directly or view it on GitHub
#86 (comment)
.

[sebastian-lenz]

The fastest way to reach a certain class/interface/module is by using the search function, you can either click on the small magnifier in the toolbar or, even more simple, you can simply start typing anywhere on the page.

I currently have two open todos that might help you with making your docs more readable:

1. Allow to specify an entry point to the documentation. Currently TypeDoc always starts the documentation hierarchy in the global namespace, it should be possible to start the documentation within a specific module, everything outside this module will be discarded. I actually have this problem with our own docs, all symbols live in the namespace td thus the index page is only showing one entry.
2. Add an index page containing all symbols. This demand has been raised by Daniel in TypeError: Cannot read property 'symbol' of undefined #70. Still have no clue where it should live in the navigation and how it should look like.

[kamranayub]

If you view our docs, everything lives under Ex but what I did was treat
that as our index page so it lists a bunch of places to start. That's one
workaround for now, but it actually works nice for us.

http://excaliburjs.com/docs/api/edge

On Mon, Apr 13, 2015, 23:50 Sebastian Lenz [email protected] wrote:

The fastest way to reach a certain class/interface/module is by using the
search function, you can either click on the small magnifier in the toolbar
or, even more simple, you can simply start typing anywhere on the page.

I currently have two open todos that might help you with making your docs
more readable:

1. Allow to specify an entry point to the documentation. Currently
   TypeDoc always starts the documentation hierarchy in the global namespace,
   it should be possible to start the documentation within a specific module,
   everything outside this module will be discarded. I actually have this
   problem with our own docs, all symbols live in the namespace td thus
   the index page is only showing one entry.
2. Add an index page containing all symbols. This demand has been
   raised by Daniel in TypeError: Cannot read property 'symbol' of undefined #70
   TypeError: Cannot read property 'symbol' of undefined #70. Still have no
   clue where it should live in the navigation and how it should look like.

—
Reply to this email directly or view it on GitHub
#86 (comment)
.

[sebastian-lenz]

A tree like navigation with expandable entries won't work very well I guess, you'd have to maintain states between page reloads and put it into some kind of scroll pane to make it user friendly. Also the size of the documentation would explode as all pages must contain the entire navigation structure, or the navigation must be generated using some script from a shared json file.

But yes, all this can be done using a custom template.

[sebastian-lenz]

@Vadorequest You've compiled the docs using the module mode, from your code sample I would guess that your project is not using a commonjs module structure. Did you try specifying --mode file when generating the docs?

[Vadorequest]

@sebastian Ho, I only was talking about the link, absolutely not about the
content of the doc itself. A tree which would be like the modules tree with
direct link to each classes/interfaces.

2015-04-14 0:04 GMT+02:00 Sebastian Lenz [email protected]:

A tree like navigation with expandable entries won't work very well I
guess, you'd have to maintain states between page reloads and put it into
some kind of scroll pane to make it user friendly. Also the size of the
documentation would explode as all pages must contain the entire navigation
structure, or the navigation must be generated using some script from a
shared json file.

But yes, all this can be done using a custom template.

—
Reply to this email directly or view it on GitHub
#86 (comment)
.

Cordialement,

M. Ambroise Dhenain.

[Vadorequest]

I'm using a CommonJS module structure, as far as I know!

Stuff like "Payline.Templating.Controllers" and so on, what makes you think
otherwise?

2015-04-14 0:10 GMT+02:00 Ambroise Dhenain [email protected]:

@sebastian Ho, I only was talking about the link, absolutely not about the
content of the doc itself. A tree which would be like the modules tree with
direct link to each classes/interfaces.

2015-04-14 0:04 GMT+02:00 Sebastian Lenz [email protected]:

A tree like navigation with expandable entries won't work very well I
guess, you'd have to maintain states between page reloads and put it into
some kind of scroll pane to make it user friendly. Also the size of the
documentation would explode as all pages must contain the entire navigation
structure, or the navigation must be generated using some script from a
shared json file.

But yes, all this can be done using a custom template.

—
Reply to this email directly or view it on GitHub
#86 (comment)
.

Cordialement,

M. Ambroise Dhenain.

Cordialement,

M. Ambroise Dhenain.

[sebastian-lenz]

When using a CommonJs/AMD structure you would do something like this to retrieve your classes:

var AbstractViewController = require('templating/AbstractViewController');

In a project built like this, the file templating/AbstractViewController.ts would not contain a module statement, instead it would simply export the class.

Specifying --mode modules makes TypeDoc insert each source file as an external module and it's contents (in your case normal modules) its descendants. If you set --mode file TypeDoc will ignore the file structure and build the documentation structure around your module structure, just like in the example of Kamran above.

[Vadorequest]

Okay, thanks for the explanation. For the record I use CommonJS but I don't
use Node or require() function at all, all these files are merged into one
which is downloaded by the browser. That's it.

2015-04-14 0:19 GMT+02:00 Sebastian Lenz [email protected]:

When using a CommonJs/AMD structure you would do something like this to
retrieve your classes:

var AbstractViewController = require('templating/AbstractViewController');

In a project built like this, the file
templating/AbstractViewController.ts would not contain a module
statement, instead it would simply export the class.

Specifying --mode modules makes TypeDoc inserting each source file as an
external module and it's contents (in your case normal modules) it's
descendants. If you set --mode file TypeDoc will ignore the file
structure and build the documentation structure around your module
structure, just like in the example of Kamran above.

—
Reply to this email directly or view it on GitHub
#86 (comment)
.

Cordialement,

M. Ambroise Dhenain.

[sebastian-lenz]

If the files will be merged you should specify --mode file. The mode parameter refers to the target output mode of the TypeScript compiler, you either compile into multiple modules or into one file.

[sebastian-lenz]

I've created issues #90 and #91 to make more clearly what has to be done. Closing this issue then.