Comments (3)
@B4nan - I see value in linking to external docs, but like you say it might be tricky to find a general way to determine the link.
ESDoc had an interesting way of solving this problem; What you'd do is you'd create a list of external definitions like this one for EcmaScript or this one for Web API. In there, you'd add types and the links they should lead to. For example:
/**
* @external {DocumentFragment} https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment
*/
/**
* @external {Element} https://developer.mozilla.org/en-US/docs/Web/API/Element
*/
/**
* @external {Event} https://developer.mozilla.org/en-US/docs/Web/API/Event
*/
Next, as ESDoc parsed the source code, it would look up any types it couldn't find in your code base in those external definition files.
I also came up with an idea to use namespaces in those definitions to avoid collisions between different external modules providing types with the same name. Serenity/JS integrates with several Web automation tools like Selenium, Playwright or WebdriverIO; they all have some flavour of a WebElement
or Browser
, so conflicts are unavoidable.
A type definition with a namespace would look something like in the example below, so <package name>~<type name>
:
/**
* @external {@wdio/types~Browser} https://github.com/webdriverio/webdriverio/blob/main/packages/webdriverio/src/types.ts
*/
/**
* @external {@wdio/types~Element} https://github.com/webdriverio/webdriverio/blob/main/packages/webdriverio/src/types.ts
*/
So what I'm thinking is that while links to external types could be disabled altogether, perhaps some form of a static dictionary could work here too? 🤔
Alternatively, if we know that the definition is external, perhaps we could define the dictionary in more general terms, like say:
`@wdio/types`: `https://github.com/webdriverio/webdriverio/tree/main/packages/wdio-types/`
However, to link to a specific line on GitHub, the external library would need to provide declaration maps.
I think it's doable, but might be tricky.
If on top of declaration maps, the external package also defined the directory
in their repository
entry in package.json
, the whole thing could work even without the explicit dictionary. 🤔
from docusaurus-plugin-typedoc-api.
Good idea, I like the @external
approach.
It would be also great to have a way to hide some of the external symbols (currently its either everything or nothing), but I guess that's more of a typedoc feature request. Like with the SessionPool
class example which extends EventEmitter
, there is too much bloat, we would be fine with having just a few methods there (e.g. emit
), most of that is out of scope.
from docusaurus-plugin-typedoc-api.
Can we at least hide the buttons if the symbol is external? Sounds better than rendering broken links and should be an easy fix, happy to send a PR.
from docusaurus-plugin-typedoc-api.
Related Issues (20)
- Update Typedoc or make it a peer dependency? HOT 9
- Monorepo with a single package is broken after update to v3.0.1 HOT 4
- Next version of the docs is not rendered with v3.0.1 HOT 3
- Symbols are not rendered as links in versioned API docs in v3.0.1 HOT 1
- Support for Docusaurus v3 HOT 2
- Docusaurus build (production) fails because of ParseError HOT 3
- Weird issue with rendering categories (using `@category` tag) HOT 3
- `VersionBanner` "cannot read properties of undefined"
- Integration into Docusaurus Search HOT 1
- Integrate the sidebar into an existing sidebar HOT 3
- Github domain(githubHost) is `undefined` in Vercel HOT 4
- Support multi-version docs gen at the same time for the same api HOT 5
- [Question] Is there a way to modify the route slugs? HOT 3
- Custom path instead of /api HOT 4
- Disable API in versioned docs HOT 3
- Object literals and destructured parameters not rendering in docusaurus HOT 5
- Internal referance to the types/interfaces are not generated HOT 1
- [Question] Is there a way to show and hide `inheritedFrom` members using a toggle? HOT 1
- [Question] Support for a "Reference" section. HOT 1
- Docusaurus 3.5 HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docusaurus-plugin-typedoc-api.