Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve nesting for navigation #2388

Closed
viveleroi opened this issue Sep 6, 2023 · 11 comments
Closed

Improve nesting for navigation #2388

viveleroi opened this issue Sep 6, 2023 · 11 comments
Labels
enhancement Improved functionality

Comments

@viveleroi
Copy link

Search Terms

navigation nesting collapse tree

Problem

The navigation gets really long for us because everything is listed as a root item rather than nested like a tree.

image

Suggested Solution

I'd rather mirror the file tree it's reading from... components would be a parent node than when expanded, shows everything inside it, etc. Then, a user would see all root categories immediately:

Components
Hooks
Stores
Utils
@viveleroi viveleroi added the enhancement Improved functionality label Sep 6, 2023
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Sep 6, 2023

There is a theme which does this - https://www.npmjs.com/package/typedoc-theme-hierarchy

With the navigation changes made in 0.25.1, this is more feasible to include in typedoc itself, but I've always struggled to understand why some people run TypeDoc this way rather than pointing it at the library entrypoint, where documentation matches the structure directly importable from the library (surely your users don't have to import lib/components/forms/inputs/date/date?!)

@viveleroi
Copy link
Author

This is entirely for our development team working within our private application. Nothing is published as a library, it's effectively a monorepo.

We can't use an entry point because there isn't one. Our app is made up of modules and they're loaded via dynamic imports based on a config and routing because modules vary by client. So when I point typedoc at main.tsx it sees some config files, some layout files, and only one exported App component. It's effectively useless.

@Gerrit0
Copy link
Collaborator

Gerrit0 commented Sep 6, 2023

Huh, and it's actually useful? I'd have expected it to just be easier to navigate within an IDE... I'll take a look at what it'll take to do this this weekend

@viveleroi
Copy link
Author

Outside of the spammy navigation the information is useful, yes. Partly because we can share these generated docs, our written dev docs, and Storybook with developers who are not yet authorized to work on the app and can't see the source. But in some cases it does a better job than an IDE - it excludes internal components/types we don't need junior developers seeing and getting overwhelmed by, and it sometimes does a better job showing all available component props especially in cases where we inherit prop types from a third party.

@viveleroi
Copy link
Author

That theme plugin you recommended works well and looks good too. I think we'll use that, thanks.

@GitMurf
Copy link

GitMurf commented Sep 13, 2023

Huh, and it's actually useful? I'd have expected it to just be easier to navigate within an IDE... I'll take a look at what it'll take to do this this weekend

Just as an FYI @Gerrit0, I have the EXACT same use case as @viveleroi. In the opposite way of it surprising you that docs on internal modules/functions/classes could be useful (as opposed to just the IDE) I am equally as surprised that there is not really a good tool/solution for this :) And I think TypeDoc has all the piping in place to be the solution for many many developers and teams. Hence how popular your awesome missing exports https://github.com/Gerrit0/typedoc-plugin-missing-exports plugin has been :)

As @viveleroi alluded to, we have a TON of stakeholders that want to understand the application and even provide feedback on business logic but have no business being inside an IDE (and would get lost in one). These docs are perfect for them to be able to review and comment on things like our data schema / types. Also having the search is very nice compared to getting overwhelmed inside an IDE.

I cannot tell you how amazing your project here is and really hope you can support some of the needs for more internal focused docs as it is a real problem in the industry and think it is a great opportunity for TypeDoc to become even stronger and more popular :)

Thanks for all your hard work!

@Plopsi
Copy link

Plopsi commented Oct 12, 2023

Typedoc is an awesome tool @Gerrit0 is developing, but the navigation gets a bit overwhelming on larger scale projects.

@viveleroi and @GitMurf comprehensed it very nicely :) - Not everything is just a library, it's quite often to have a seperate code-documentation for bigger projects. The documentation works well, but navigating in the project gets hard without a "foldered" navigation

I guess it would alone be helpful to just have nestable '@group' and/or '@category' options like '@group my.nested.group', which then is nesting in the navigation.

The plugin is nice, but produces a ~8GB ouput as it puts the navigation into every page (anyone though every about putting the actual doc-pages into an iframe and let the navigation reside in the index.html?) - in comparison of around 120MB with pure typedoc.

  • Plopsi

@Gerrit0 Gerrit0 added this to the v0.26.0 milestone Oct 15, 2023
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Oct 15, 2023

I've been experimenting with changes to how pages are generated, and I think the navigation fits well into this, will be a part of 0.26, which may still be 6 months away

@citkane
Copy link
Contributor

citkane commented Oct 22, 2023

I developed a theme a while back for typedoc that efficiently presents hierarchically:
https://citkane.github.io/typedoc-theme-yaf/dev/

I stopped developing at the switch to typedoc 0.24 because my logic was too fragile for the changes to the API.
Basically:

  • all pages are stored as .json data fragments (instead of html) and loaded on demand
  • all rendering logic is in the frontend, which is built with native web components
  • the menu data is only loaded once

You may (or may not) get some ideas from it.

@Plopsi
Copy link

Plopsi commented Oct 23, 2023

@citkane whooo nice... i like it, the grouping/categorizing is just missing :) - i guess then it would fit exactly - except that i don't like the design ;D - I like the show hidden feature....

  • Plopsi

@typhonrt
Copy link

@viveleroi and others...

I have just released the next beta of my "Default Modern Theme" (DMT) augmentation for the default TypeDoc theme. This takes full advantage of the new navigation index capability of TypeDoc 0.25.1+. The original DMT release in July spurred the creation of the navigation index for TypeDoc 0.25.x. The latest DMT release is fully ready to go, but I just want to get a little feedback before releasing 0.2.0, so if anyone has the gumption to try it out I'd be glad to get feedback (open an issue on the DMT repo).

package.json:

{
   "devDependencies": {
      "@typhonjs-typedoc/typedoc-theme-dmt": "^0.2.0-next.1",
      "typedoc": "^0.25.0"
   }
}

typedoc.json:

{
  "plugin": [
    "@typhonjs-typedoc/typedoc-theme-dmt"
  ],

  "theme": "default-modern",
}

My main OSS project is putting out a large framework for Svelte. The API docs covers three NPM packages. My framework uses many sub-path exports so without the full navigation tree of the DMT there is like ~65+ modules represented in the default TypeDoc navigation index; a situation similar to what @viveleroi brought up w/ their effort. The latest DMT vastly improves navigation across the API docs and understandability as well.

You can check out the generated docs for this framework here w/ the latest DMT for an example:
https://typhonjs-fvtt-lib.github.io/api-docs/

The DMT by default creates a full tree for "modules" that are otherwise concatenated in the default navigation index. You have control over the navigation index though and can decide at which depth concatenation starts.

The theme option dmtNavModuleDepth controls at which depth module path concatenation occurs. If you set that to 0 then there is no path concatenation and the output is just like the default theme. Set it to 1 then there is one level before concatenation occurs. You don't have to set this option though as a full navigation tree is generated by default.

There are many other neat features of the DMT and I'll be expanding on documentation and put out a video tutorial in the coming weeks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality
Projects
None yet
Development

No branches or pull requests

6 participants