Replies: 25 comments 2 replies
-
|
Not everything is suitable for upstreaming to the default TypeDoc theme, but I think there are areas that can be accepted to improve the default theme. Some of the obvious aspects are style changes to clean up the default theme as that may make sense. Another procedural one that I'd like to see that is very specific is a better way to handle the inline SVG for the various reflection kinds: namespace, function, etc. The SVG elements that display in the default theme per page. Right now the first usage of the SVG for a particular reflection kind has the full element and all successive usages refer to the original embedding. It would be great to either have all SVG / reflection kinds cached on the page or have them as external resources that can be loaded. A major reason for such a change is that you can not refer to a reflection kind that is not already in the page due to the way that only the SVG for reflection kinds in the current page is available. For instance I plan on continuing to improve the main search index and offer a new "quick search" UI and it would be nice to show the SVG for any reflection kind found in the respective search UI and that may include reflection kinds not presently loaded on the current page, so externally hosting this SVG is useful. Anyway.. There is a lot to potentially discuss. The technique or approach I took w/ the "DMT" I think is relatively unique. I'm going more for augmenting the output of the default theme than purely replacing it. The general hope is that I'll be able to keep things synched w/ the default theme as it continues to change and use the DMT as an advanced prototyping stage to then upstream whatever makes sense. |
Beta Was this translation helpful? Give feedback.
-
|
Very delayed response here on my part, apologies for that! You have built something really cool here. I agree with your assessment that at least some of these changes ought to make it into TypeDoc's default theme, and just finished reworking navigation to be built dynamically. With this change, the DOM library is 185mb with TypeDoc's default theme, and I haven't compressed the search index yet! Incidentally, this required that I require all icons be embedded in each page. I looked at having them in an external page, but unfortunately this seems to make it impossible to style them properly for theme changes, so with 0.25.1, they'll all be there! |
Beta Was this translation helpful? Give feedback.
-
|
No worries on the delay. I'm just ramping up for my next OSS dev cycle Oct-Dec. Definitely appreciate the nod on what I created. The I'll definitely spend some time w/ the latest TypeDoc release soon to see any changes and start to evaluate what can be upstreamed from the DMT / theme effort as well.
For some of the features I have in the DMT theme I had to do some shuffling of the icon definitions. If all of the icons are present on the page in a separate reference section that can work too. I think I'll have more input in the second half of October, so definitely would like to circle around and see what is possible to upstream in that general timeframe. |
Beta Was this translation helpful? Give feedback.
-
|
@Gerrit0 I spent a lot of time on this one ~160 hours and really honed a lot of things I'd like to upstream into the default theme as it makes sense. Beside the detailed navigation index work one area that I spent a lot of time on is accessibility / keyboard navigation as well as honing styles / CSS to make keyboard navigation more intelligible. Let's continue the discussion as I'm open to actually contribute / upstream what makes sense to do so. 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
{
"devDependencies": {
"@typhonjs-typedoc/typedoc-theme-dmt": "^0.2.0-next.1",
"typedoc": "^0.25.0"
}
}
{
"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. 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: 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 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. |
Beta Was this translation helpful? Give feedback.
-
|
Accessibility and keyboard navigation improvements would be very much appreciated! I am rarely working in the frontend with the exception of this project, so know that I tend to miss things. The nested navigation by splitting on |
Beta Was this translation helpful? Give feedback.
-
|
Yeah.. Let's try and find a way to actually upstream various aspects of the DMT that are applicable. I'm definitely willing to become a direct contributor. Styles / CSS is relatively low hanging fruit for sure along with potential template modifications. There aren't too many in this category, but a few places that extend flexibility / use of flex box wrapping elements, etc. Re: navigation index changes. I certainly have the code worked out for modifying the current navigation index generated to provide nesting. There is an option There presently isn't an "auto-concatenate" option to concatenate singular paths like The only "major" config related HTML structural change w/ the latest DMT is that The main angle of upstream consideration is potentially switching over to a compile time library / framework. I have a preference for Svelte / use it currently in the DMT. It really does give a bit of extra polish over the homegrown "light component" wrappers IE: Regarding the navigation index. In the DMT I make it into a data structure that is stateful and queryable. There are a lot of things that the current default theme implementation misses in this regard. Try loading any URL with a hash fragment for an internal symbol to a given page. The default theme doesn't correctly select the navigation element in this case, etc. So lots of little things are a bit disconnected in the current default theme. The DMT will run a couple of queries with and without the hash fragment to find the correct page / NavigationElement entry to select, etc. With the forthcoming I think it is good to have a comparison w/ the DMT regarding polish / final fit and finish as a way to show where the default theme can go. Since it is an augmentation of the default theme output vs a replacement the DMT provides a bit of a clearer picture on where things can potentially be improved. Ooo.. I also have something spicy incoming shortly for an automatic CLI for doc generation from |
Beta Was this translation helpful? Give feedback.
-
I am not a frontend enjoyer, I have really only one hard rule for the default theme. The site shall work without JavaScript. It might not be perfect (search, filter, full navigation tree), but it will at least be readable. Frontend frameworks seem to all be of the "render everything" opinion rather than being built for progressive enhancement. A second goal is that adjusting something in the theme should not require understanding a massive framework. Everything I've used (Svelte isn't on that list) has always had annoying edge cases to fall into that end up compounding the DOM's weirdness... |
Beta Was this translation helpful? Give feedback.
-
So, I got everything working again w/ no script loading for the DMT. I'm sure you have noticed with the default theme the visual flash and inconsistent state of the UI as the additional default theme JS is loaded. This is very noticeable w/ the "settings" / "on this page" accordions depending on state (if they are closed) and the navigation tree will flash and readjust as the default theme JS loads which can be very jarring depending on the state and how large the navigation tree is. The same will happen w/ loading Svelte components in regard to enhancement just after the initial page loads. To get around this visual glitch I add additional style rules to I have made the adjustment so that there is an additional So the DMT loads fine without Javascript enabled. The same minimal HTML navigation tree output by the default theme is what you get. On to your second point. Just like the bespoke loading of JS w/ the default theme "lightweight component" API my usage of Svelte is exactly the same where I just target the navigation index and search components. It just uses Svelte instead of the bespoke mechanism of the default theme. Folks that want to modify the default theme will have to understand your bespoke API regardless, so it's not a standard per se. I think it would be a minor nightmare to reproduce the UX / interactivity and accessibility support that the Svelte navigation component brings to the table with the default theme "lightweight component" API. Using Svelte doesn't mean the whole page is rendered w/ Svelte. It is surgical in implementation and the nice thing about Svelte being a "compile-time" library / framework is that a single all contained bundle is produced for loading; IE no additional runtime to load (Vue / React, etc.). Do you know of any themes that continue to use the "lightweight component" API that you built for the default theme? My guess is that most replace those aspects with other tech or don't touch it at all. I think a good way to evaluate the DMT is whether one feels the UX and features improve on the default theme regardless of the underlying tech. |
Beta Was this translation helpful? Give feedback.
-
|
I haven't kept track of what themes people have built besides making sure appropriately tagged ones show up on https://typedoc.org/guides/themes/ Some thoughts, in no particular order, I haven't played with it much on desktop yet:
|
Beta Was this translation helpful? Give feedback.
-
|
So the latest DMT is out The major performance win in the latest DMT release is that the SVG icons cache is stored as an external file and the per page cache is removed which saves 15KB per page which really can add up with large documentation projects (20-30%) of file space. Responses to the previous post: I definitely want to reiterate that the DMT is not in a final state in respect to potential upstreaming nor would it potentially just be adopted. It is an attempt to deliver maximum value w/ minimal structural changes. A few things that you listed would require more involved structural changes that is more appropriate in the theme replacement category than augmentation. The DMT is more of a guide of where significant updates can occur with the default theme. I am more than willing to work on a full upstream effort to incorporate these changes in the default theme.
Definitely a Safari / iOS thing. I increased the font-size to 16px which should stop this default behavior on iOS. I gather the default theme does the same as there is no font-size set.
If you can provide a bit more information / screen shot that can help in this case. It is not clear exactly what you are referring to.
Just like the navigation guide lines the additional parameter list overlaid borders / background shows depth so you can easily tell which parameter list is being viewed quickly. Granted this is a subjective change, but the grouping / borders helps quite a bit when scrolling through large files with lots of methods.
This is now enabled. Clear local storage and you'll see that the
Yeah... The change is that the main content div is now scrollable versus the whole page. This does favor the desktop display in this case, but this change also significantly improves the left hand navigation which is a bit "wonky" w/ the default theme; not being pejorative there. You can also on mobile devices flick up / down the docs title bar to hide the mobile browser URL bar.
This is one of those augmentation vs replacement issues. The main problem with the default theme is the absolute positioning of the search button and overflow mobile menu. In a more replacement oriented solution the search and mobile overflow buttons would be part of a flex box in the title bar. If you really want to ensure folks w/ less than ~420px wide devices have no problems then a custom icon fly-out Svelte component is the best solution. IE once there is not enough space for all the icons they are condensed down into a fly-out overflow menu. Again that really would only come into play with folks reading documentation on their smartwatch.. :O Presently the
I made the default brighter. A CSS variable is available to change it further.
|
Beta Was this translation helpful? Give feedback.
-
Neat! The exports handling sounds like exactly what I want to include in TypeDoc someday.
I've wanted to do this for a while, didn't realize it was so easy to do! Going to steal that right now..
Surprisingly, it doesn't... frontend is a mystery to me. Potentially due to the font-size on body?
This appears to be another safari specific thing, I can't reproduce on desktop - visiting https://typhonjs-fvtt-lib.github.io/api-docs/classes/_runtime_util.Hashing.html#hashCode results in this: (Icons inside the circles are consistently off center as shown in the image as well, same for the dropdown expand/collapse) Image
👍 very nice
Having played with it some more, I'm coming around to this change, it still feels a bit noisy when dealing with callbacks, but for the majority of members, I definitely like it.
Very unfortunate if that's a necessary change... It's fine on most pages, until I get to one where there's just enough content to hide content behind the navigation bar (ComponentProps on my phone), then the page gets quite wonky. What wonk are you referring to in the default theme? I thought I'd brute forced my way through all the issues there.
My non-massive phone is 375px wide according to Firefox devtools, it's not too uncommon for me to use it for a quick reference if talking to someone on Discord. Definitely agree that the default theme does no better, and in many ways worse.
Much easier to see 👍
Definitely makes sense. Having played with it a bit more, I don't mind the alt based shortcuts, though it isn't really true to say that because it uses Alt, it won't conflict - Alt+T+I opens Firefox's Page Information dialog. Esc should definitely close the search bar. I especially like Alt+C, though it makes me wonder if the "reflection summary" interface block on pages like this one should have an anchor to skip them. Now, the elephant: TypeDoc's default theme really hasn't changed structurally in any significant way since I started working on it ~6 years ago. The two biggest changes were moving from handlebars to JSX (which didn't actually change the output structure, just made it much easier to detect type errors) and a styling rework which made browsing on mobile much better, and fixed a lot of accessibility problems. Is it time for that to change? You're clearly passionate about making docs better, which is awesome. If you think it is time that TypeDoc's default theme was rebuilt, and want to lead that effort, I'd be happy to add you as a contributor and provide what help I can, we'd definitely want to do this as a part of a minor release. |
Beta Was this translation helpful? Give feedback.
-
Re:
Indeed I missed that aspect during development as I use WebStorm and it runs a local web server behind the scene when you open HTML files directly. Upon investigation it indeed is a run of the mill CORS issue and there doesn't appear to be a work around for opening the docs locally without a web server when externally referencing the SVG icons. The good news is something like this can be optional and is easy to turn on / off at least w/ the DMT. Also these days it is easy to configure a local web server. That could be incorporated into the I think it is important to consider the deployment aspects of generated documentation and prioritize production use cases over broad "it has to work everywhere no exceptions" mindset. With a flag / option to externalize the the SVG icons this allows production use cases ending up w/ ~20-30% less disk space and network bandwidth which are important cost factors especially with large documentation efforts.
It's certainly good that you have a small form factor device to test with. The solution here is to redesign the structural layout such that there is the fly-out icon component that can reduce the icons to a single button in addition to making the search and overflow mobile menu a part of the the flex box layout added by the DMT. Also when doing this the documentation title can also use overflow ellipses such that the any fly-out icon component, search button, and mobile overflow button is always visible and if the documentation title is abbreviated via overflow that is just the situation with a small form factor device. The present state of the DMT is still an interim solution where I'm not as heavy handed in changing the structural aspects of the absolute positioned search / mobile overflow buttons. I'll look into creating the above better solution before I launch DMT
👍
The DMT implementation is a subjective change to make things cleaner. I have a general idea what you are trying to work around in regard to the browser URL title / popup in the bottom left corner. I haven't used Safari much, but for instance Chrome moves this popup away when the mouse navigates toward the bottom of the screen. The work around of making the left hand navigation floating and then having extra space at the bottom after scrolling down is a work around for a particular browser that you use. Here is what Chrome looks like in regard to moving the mouse / cursor over the URL popup at the left hand bottom of navigation. You can see that it moves this popup down / away from the cursor: chrome-url-popup.mp4
It's definitely worth working out the aspects commented upon from the main header toolbar to other use cases where small form factor is a consideration. Assuming everyone has modern phone is not globally ideal either. I believe that the forthcoming additional efforts mentioned above will get things there.
And it doesn't.
I don't think that is a problem as the breadcrumb header gets focus on that particular page. Also follow up tab navigation works through the interface block where they can be selected. So no particular need to skip them.
I don't think so when it comes to static HTML generation. When I mentioned structural changes I was referring to HTML structural aspects where a few more specific changes to the HTML structural output will improve solutions like the top header bar / buttons / icons. I didn't make these kinds of more involved changes to keep the changes I do make to ~300 lines of code and a bit more resilient. In the upstreaming process I'd convert the bespoke modifications that I do in the DMT to The aspect of swapping out the bespoke scripting API ala
I'm definitely open to contributing, but also doing it in a proper / controlled fashion with lots of documentation. From a timing perspective I think targeting something like this for the end of '24 is best. This gives ample time to continue iterating on the DMT to really fine tune it and in many respects it'll be known exactly what may change and what the results will be before upstreaming. Svelte 5 is soon to be released, so I'll be updating the DMT to use it in the coming months, so this also fits well w/ an end of '24 timeline. I also have my large OSS projects that I need to get back to servicing. I spent the last two months in the TypeDoc / tooling space and developers using my other projects are waiting for a release or two. |
Beta Was this translation helpful? Give feedback.
-
Why two binaries? I was thinking that TypeDoc would use the package.json handling by default if no entry points were provided manually by the user.
True, I don't love needing an option here, might experiment with adding a script that's only loaded for
I wish this is what I was working around! The smaller nav size there is actually to keep the entire scrollbar on the screen since it doesn't start directly adjacent to the header bar Safari on mobile is unfortunately very annoying to optimize for, the entire url bar + navigation buttons at the bottom of the screen in the image I sent earlier will collapse if the page is large enough to scroll down, there's a specific page size for which this doesn't work on the DMT.
This is exactly what I meant by structural changes, apologies, that was rather vague.
👍 sounds good, gives me some time to try to improve the theming code to be more understandable in the meantime. |
Beta Was this translation helpful? Give feedback.
-
A separate CLI... Allows flexibility for changing environments; while Node / There are alternate solutions like turning the TypeDoc CLI into a multi-command CLI which is better than stuffing too many competing flags / options into a single use CLI. Re:
Experimentation is good of course, but that is a pretty big commitment to deploy. I don't think it's as much of a concern though over other features / maintenance, but gathering some metrics in that regard is useful. A flag / option for enabling offline usage is easier with production deployment being the default. It should be possible to gracefully fail and show informational resources regarding a given production doc deployment when opened locally. Indeed the main "problem" with the DMT is ESM deployment.
Not having the same device you do gives me a bit of a handicap in discussing this aspect. The DMT is fine on any standard / modern phone & tablet (Android tested on my side w/ recent PIxel tablet and a Pixel 4 phone). Optimizing things for your specific small form factor mobile device / OS over the desktop environment is what it is. I'd say though that it's more important to optimize the desktop experience. The DMT works well on 4K monitors vs the default theme for instance. I'll give it a good shot in fixing up all the final tweaks I mentioned above which should alleviate most small form factor concerns. I'm not opposed to picking up a used iOS device that is similar to what you are working with...
Yeah, let's stay in touch. I'd be glad to upstream everything that makes sense as there is no particular reason to recreate the wheel. I'll probably open another discussion thread about subtleties detected in recent TypeDoc releases. For instance the full hierarchy view crashes with |
Beta Was this translation helpful? Give feedback.
-
|
Hiya @Gerrit0... I have updated my TypeDoc theme (DMT) and plugins for the latest In brief I do have a lot of critical feedback on various aspects since we last chatted regarding perceived UX issues with new features as currently implemented in the mainline default theme, but also other internal API changes that affect 3rd party developers; some of the latter not even receiving a mention in release notes. I'd be glad to continue discussing these issues if you are interested as well as a possible pathway to mainline some of the DMT features in the future. While there are aspects that could be inspiring to take and implement within TypeDoc I'd really like to find out if there is a way to unify particularly my frontend dynamic work into the mainline release. Perhaps to start some video demos of various UX refinements to new features. In particular the separation of additional Markdown documents into a unique navigation tree and synchronized document content folding between the main content area and This demo video shows improvement to the DMT icon links where if there is not enough space (mobile vertical orientation) they will collapse into a hamburger menu: You can view hosted generated docs with the latest DMT here with my proposed |
Beta Was this translation helpful? Give feedback.
-
This doesn't surprise me too much, it is entirely too easy for people to end up using parts of TypeDoc which are not considered part of the public API, and with the HTML output in particular, every small change has the potential to break things in ways that can't be caught by a type checker. Documenting every change to internal functions isn't feasible... if there are specific instances you think should have been documented, I'm not opposed to including addition entries in the changelog/releases, though updating the releases is an unfortunately manual process.
For projects which have top level project documents and an API package, I'm leaning towards agreeing with you. However, this does not cover all documents! That feature very intentionally allows users to include markdown documents at lower level areas, for example TypeDoc's Internationalization namespace also includes a related document. How does the DMT handle this? Similarly, if you have documentation for more than one package included in one site, each package might have documents specific to that package. Something I should mention is that your typedoc default theme output has the unfortunate consequence of my forgetting to set the default
I considered doing this when adding the folding, and decided against doing it, it seemed confusing to me at the time... having played with your update for 20 minutes or so now though, I quite like it. Definitely something that'll come to the default theme.
Very nice, this is exactly the type of tweak that I have absolutely no desire to add myself, but greatly appreciate when someone else makes it happen. Upstreaming: There are a fairly small number of things that'd need to change for me to be happy to just adopt the DMT as TypeDoc's default, assuming that the handling of non-toplevel documents is reasonable. Parts of it have really grown on me, including the keyboard shortcuts being awesome. I also really like the inclusion of the class hierarchy in the main navigation as a link.
There are a few minor things that still feel somewhat off about the DMT to me, but I'm not really opposed to, including:
Another thing you might like, I'm considering a different rendering strategy for modules in 0.27: Re-exports have the arrows, and the first paragraph (or
|
Beta Was this translation helpful? Give feedback.
-
So, from previous conversation you mentioned you have no visibility into what 3rd party developers are doing and this is a general problem. The In fact that particular commit, Typed event emitters, in between Something that will help in these matters is for you to make Not condemning here. Just pointing out there are options to make beta releases and potential
Yes, it took me 5 weeks! fulltime to update the DMT to
Often your changes and additions seem a little scattershot. Less is more and you'll certainly hear me repeat this at the end with your additional proposed changes below. The DMT completely handles the
One can use
IMHO having a complete separation in the GUI that doesn't alter the source navigation index particularly fabricating a module where non-exists is really important. I get that this was the "easiest" way for you to implement the new feature by just stuffing it into a single navigation tree, but it's not good UX and obscures package / source code structure. Various options for the single navigation index for categories and groups makes it much worse. The DMT handles all permutations and cleanly separates the markdown documents as well as removing the fabricated
Please try and implement that in the
It's easy on my side because of Svelte and I have a larger library of utility functions / Svelte actions that make it streamlined to hookup ResizeObserver and such. Still a unique problem though in pre-calculating the image widths.
I appreciate the nod. Hopefully my comments don't come across as too critical. If they seem charged it's just because I have spent ~4 months in the last ~1.75 years working explicitly on TypeDoc related efforts instead of my actual projects that really matter and are being underserved as a result with devs waiting / not happy generally. I've spent over $20k of my own funds (IE keeping the lights on / bills paid) in this time effectively in this effort. I am glad though that we might move forward with mainlining and making all that effort turn out positively.
Just take a moment to understand that this is a side effect of using modern ES Module loading. ESM requires for increased security purposes that a web server is used. I have provided clear instructions on several easy ways to handle this situation in a wiki post. I gather you don't use a modern IDE like WebStorm or VSCode which has built-in web servers and the docs can instantly be opened directly from the IDE. Please take note that it is super easy to start a static web server given that one already is working with Node / NPM for TypeDoc in the first place. You just need a one line script like: {
"scripts": {
"sirv": "npx sirv-cli docs --host"
}
}
I'm strongly in the ESM first / work with modern technology camp. That doesn't mean I can't find a way to work around and generate an IIFE for the DMT, but at some point it's just a good idea to adopt modern technology.
I'll look into it. I don't expect any complications.
There is no posted information on how a 3rd party plugin (or I missed it) can interface with the new i18n API. I'm sure it's possible, but I haven't taken the time yet.
Yeah, definitely on the subjective side of things. The drop shadow just visually separates the right column from the main content. I'm not married to it, but that is why I added it.
I was thinking of a way to keep this in and likely the solution is to add another button in the header bar when in reduced width mode. It's just too much / long of a column to put that on top of the source code index in the mobile menu which is higher priority.
Here I am definitely going to advocate for less is more. Particularly for more randomly generated content in the module pages. It is definitely not guaranteed that picking the first sentence / paragraph for any given reflection will result in quality output. It will really be an eyesore for complex projects yet may seem like it's an improvement for smaller projects. I'd gate this behind an option and have it turned off by default until feedback can come in and effectiveness evaluated for all sizes of projects. Even for I need to better understand the A bit long here, but yeah. Let's definitely continue the conversation. As far as mainlining the DMT goes I need to focus on my actual projects and get release out in the coming 1-2 months and can once again look at things in ~December timeframe. Generally I'd suggest working on non layout effecting features as there are many things that can be tightened up without tweaking the layout and such more for the next release. This will just make integrating the DMT easier. |
Beta Was this translation helpful? Give feedback.
-
I can't agree with this. When making changes I suspect might be breaking I check
Notably, your DMT theme was not in that list as it was not at the time properly
All of those changes are listed under a
(breathes) Removal of (so far as I was aware) functions which were completely
This feels like an annoying amount of overhead for a hobby project that gets a
This ought to produce a warning today that it isn't supported there. I thought
Because it does different things!
For your use cases, sure. However, I have seen projects, and have had feature
Yes, and it is incredibly unfortunate that to use ESM and fetch one must give up It's not that I can't set up a web server, so much as it's an extra step that
https://typedoc.org/api/interfaces/Internationalization.TranslatableStrings.html
I definitely plan to put the first paragraph "implicit summary" behind an option.
The opposite, re-exports in that picture are documented with the arrow pointing
Unfortunately this somewhat conflicts with the issues I currently have worked/am |
Beta Was this translation helpful? Give feedback.
-
I'm not really commenting on keeping the event API here. That is fine because there is a replacement / comparable API. That is not the case with
It is totally fine to do this as you have to explicitly follow releases to get notifications anyway. I follow Svelte 5 releases and they are on pre-release 259 with almost daily updates for the last year. Considering for TypeDoc that is ~3-6 beta releases then an RC before final that is low bandwidth for those that need to track progress. For 3rd party devs getting notifications of all releases beta through RC and final is useful.
It would take ~30 lines of code granted with a multi-command CLI to make That being said to not rock the boat I will look into an IIFE approach, but it's just technical debt / convolutes things IMHO.
👍
While one is internal API change the other two seem to deal with content and not the macro layout of the docs. I'm more concerned about layout aspects changing between the main column, header, sidebars, and footer. So a relatively quiet period for those aspects would be handy. Let's keep the conversation going hopefully My next window for TypeDoc efforts is likely in December. |
Beta Was this translation helpful? Give feedback.
-
Sorry, I was not clear -- the event emitter change was what drove removeComponent. It was implemented through inversion of control on the emitter class.
Fair enough, I'll think about how to do this in a way which isn't a pain to maintain... I really like how simple it is to make a release/beta release today, but someone has probably made decent automation for it since I set up the original system 4 years ago.
The only potential change there is #2630, which I doubt I'll work anytime soon, narrator isn't fun to wrok on.
👍 Will probably be the change for 0.28 then, I'm hoping to get 0.27 out before then |
Beta Was this translation helpful? Give feedback.
-
|
Not going to work it now, but putting it here as it is something that I think probably would greatly improve the docs for some use cases. If a library references types declared in a dependency, sometimes that dependency might not have a generated doc site. In that case, it may make sense to generate docs for that dependency, but they really probably ought to be more visually separated from the "real" docs than just including a namespace for them. |
Beta Was this translation helpful? Give feedback.
-
|
Great work on the That being said my next possible window to integrate the DMT is April-May. Various things of slightly higher dev focus need to be sorted out first on my side. I also need to convert my Svelte 4 framework to Svelte 5; it's a bit of a "paradigm shift". I have a strong preference to do things right the first time and don't want to have to take a second pass with the DMT to upgrade to Svelte 5 afterward. With everything on my plate April & May should be possible to clear things out to work 100% on the integration. I'm of course keeping the DMT on pace with TypeDoc updates until then. At some point it will be really handy to have a bit more in-depth discussions and make sure we are on the same page. There are of course some design decisions I've implemented that differ from your preferences, so minimizing surprises ahead of time is best. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks! With 0.27 done, there's very few issues left open that need work, it'll be nice to effectively be done with a project for once. It scares me that in 2024 there are still paradigm shifts for frontend development. TypeDoc is mostly a static site, with a fairly small number of JS-required features... |
Beta Was this translation helpful? Give feedback.
-
|
Good move to a discussion instead of an issue. Not much to report other than I have my head down working hard trying to be ready around April for integration.
I think the broad strokes are done, but there is a bit of fine tuning. An example on the CSS styles side of things is to minimize the use of margin for spacing elements and use more modern mechanisms that are now available like flexbox + gap. I have an interesting issue to file soon for you to take a look at regarding re-exports not being detected as re-exports across package boundaries when
Well, wait until you see what's coming to JS in the near future. ES2026 might be a banger. ;) In respect to Svelte though v5 is a massive rewrite / new way of working with Svelte. I have a lot of code to convert / update and need to get my framework Svelte 5 compatible ASAP before I can work on the TypeDoc integration. |
Beta Was this translation helpful? Give feedback.
-
|
Gah, apparently discussions means that GitHub doesn't give me notifications about these anymore! That needs fixing...
This is likely introducing a new symbol, might unfortunately be a design limitation, in a similar way to how the following isn't a re-export: import { foo } from "lib";
const bar = foo;
export { bar } |
Beta Was this translation helpful? Give feedback.
-
|
I did get an email for this comment of yours, but that's probably because I've followed you on GitHub |
Beta Was this translation helpful? Give feedback.
-
|
This reply gave me a notification, so hopefully I've fixed it now |
Beta Was this translation helpful? Give feedback.
-
I'd like to discuss aspects that are worthy of committing back to the default TypeDoc theme from the recent work that I have released that addresses some general issues. I will include a general announcement below about the resources I have released followed up by aspects that could make it back to the default theme.
The big performance gains are ~90% less disk space utilization and ~80% faster doc generation over the default theme.
I also posted a quick overview video of the resources discussed:
https://www.youtube.com/watch?v=P-TUSPbtLQ0
I have just released a few projects that might help your TypeDoc related usage; particularly for large project documentation generation w/ TypeDoc. I have created the "Default Modern Theme" / "DMT" and its what I call a "theme augmentation" package that functions by augmenting the output of the default TypeDoc theme instead of entirely replacing it. It saves up to ~90% of disk space utilized and is ~80% faster than generating docs w/ the default theme. I also have a few stylistic additions that make things just a bit nicer and increased a11y support with more to come.
Here are the resources to review:
Typedoc Theme (Default Modern Theme)
https://www.npmjs.com/package/@typhonjs-typedoc/typedoc-theme-dmt
Complete and linkable API docs for the TS built-in library declarations + WebGPU / WebCodecs / WebXR APIs. When you generate docs you can add an additional set of TypeDoc plugins to link to every symbol in the declarations to your project docs.
https://www.npmjs.com/package/@typhonjs-typedoc/ts-lib-docs
Jump right to the hosted TS lib docs for an example of large projects generated w/ the DMT:
DOM + WebGPU / WebCodecs / WebXR,
ES2023,
Web Worker APIs.
The TS lib API docs also cross link every symbol against the MDN browser compatibility package and provide links to MDN and relevant specifications integrated in the API docs.
Check out the README and the configuration descriptions available in the links above.
Background:
The main bottleneck with the TypeDoc default theme especially for large projects is the verbose HTML for the left-hand navigation that linearly grows for each page based on the project size and consumes a massive amount of disk space; see this TypeDoc issue. The DMT caches the left-hand navigation HTML and dynamically creates a shared web component that is utilized across all pages only making a single copy of the navigation HTML. This reduces disk space utilization by up to 90% and also makes doc generation ~80% faster. I also include some style additions and replace the main search index generation using compressed MesssagePack instead of JSON which reduces the search index size by more than 90%.
The TS lib DOM API for instance is over 1.4GB with the standard default TypeDoc theme, but w/ the DMT it is 137MB. Well within the size to host on Github Pages.
Being that these resources are new I did "soft-launch" the TS lib API docs using Github Pages for hosting. If things take off and it becomes a popular global resource for documentation generation / linking I will likely have to find a more permanent host. So just a heads up that possibly sometime in the future the hosting location may need to change.
Feedback:
I'd be glad to hear feedback on how I can improve theses resources! My general plan is to try and upstream as much as possible back to the Typedoc default theme over the coming months and continue to add usability features including better search capabilities for large projects to the DMT.
Beta Was this translation helpful? Give feedback.
All reactions