Warning
This repo has been archived, please use the deno doc --html
command or the deno_doc
rust crate.
A set of components used to render deno_doc DocNodes.
The repository contains a showcase application to see example rendering of the
components in the _showcase
directory. It can be run locally using:
> deno task showcase
It is also available on deno-doc-components.deno.dev.
There are other services that may need to be provided to integrate the
components into an application. These can also be provided via setup()
and
will override the default behavior.
The function href()
should return a link string value which will be used at
points in rendering when linking off to other modules and symbols. It has the
following signature:
interface Configuration {
href?: (path: string, symbol?: string) => string;
}
The path
will be set to the module being requested (e.g. /mod.ts
) and
optionally a symbol
will be provided, if targeting a specific exported symbol
from that module.
The function lookupSymbolHref()
is used when the components are trying to
resolve a link to a specific symbol. An implementation should attempt to resolve
the symbol from the current namespace to the current module, to the global
namespace, returning a link to the first matching symbol it finds. If the symbol
cannot be found, undefined
should be returned.
interface Configuration {
lookupSymbolHref?: (
current: string,
namespace: string | undefined,
symbol: string,
) => string | undefined;
}
The current
will be set to the module that is the current reference point
(e.g. /mod.ts
), any namespace
that is in the current scope (e.g. errors
)
and the symbol that is being looked for (e.g. Uint8Array
). If the current
namespace is with another namespace, they will be separated by a .
(e.g.
custom.errors
).
twind has some shared hidden state, which means that doc_components needs to
share the same versions of the remote twind modules. In order to do that,
doc_components
from the bare specifiers twind
, twind/colors
, twind/css
.
Also, if you are setting up twind to SSR in a client application, you will end
up needing items from twind/sheets
.
Therefore it is expected that you will use an import map to provide the specific version of twind you are using in your end application. This repository contains an example which is used for the showcase.
You can specify a twind setup configuration by passing a property of tw
when
performing a setup. For example:
import { setup } from "https://deno.land/x/deno_doc_components/services.ts";
await setup({
tw: {
theme: {
colors: {
transparent: "transparent",
},
},
},
});
The /services.ts
module exports a theme
object which is the default theme
settings that the doc_components
use with twind, which can be used when you
are performing setup from twind yourself:
import { setup } from "twind";
import { theme } from "https://deno.land/x/deno_doc_components/services.ts";
setup({ theme });
Copyright 2021-2023 the Deno authors. All rights reserved. MIT License.
doc_components's People
Forkers
bartlomieju meszarosdezso hashrock magurotuna jespertheend bodograumann aninternettroll lino-levan justjavac sigmasd seanpm2001 deerdoc_components's Issues
Root module should not be "expandable"
reduce the usage of `tw`
In dotland we migrated Fresh >= 1.1 (ref denoland/dotland#2554). So now we don't need to use tw
notation in components' class
props.
default exports missing from module doc pages
For example: https://deno.land/x/[email protected]/mod.ts
bug: doc index looks kind of janky
Hitting refresh causes pages to mis-render
@crowlKats notices that independent of JSX library, that when things are refreshed the server appears to be holding onto state the causes the pages to mis-render.
Copy button on import statements not working
Document pages provide us with copy buttons allowing us to copy import statements easily. For instance you can see one here: https://deno.land/[email protected]/fmt/colors.ts
Turned out that this button did nothing. I quickly looked into it to find that the onclick
attribute is set as a string with weird newline as well as unintentional escape characters of double quotes ("
is converted to "
).
<button class="tw-wu5gnb" onclick="navigator?.clipboard?.writeText("import * as mod from "https://deno.land/[email protected]/fmt/colors.ts";
");">
I'm pretty sure we need to carefully construct the value for the onclick attribute so that copy buttons work as expected. I suppose the straightforward way to fix it is to use client-side JavaScript to set the click handler instead of using string in the onclick
attribute, though I'm not sure if it's the right direction.
Doc View Nav should render deprecated symbols differently
display multiple symbol kinds as one symbol in module doc
Follow up to #50
Code block spacing with private
Index Component should collapse table in mobile
The Module Doc component collapses the two column when in mobile, Index page should as well.
Markdown component throws if a code block has unregistered language
The below lowlight.highlight
call seems throwing error if the language is unknown.
doc_components/doc/markdown.tsx
Line 31 in 782b6b8
This causes error in the following page:
Support JSDoc `{@link SomeClass#method}`
https://jsdoc.app/tags-inline-link.html shows links in the format {@link SomeClass#method}
, but deno_doc (or deno.land?) doesn't seem to support that format.
For example, at https://deno.land/x/[email protected]/mod.ts I just see
which is getting rendered as:
Add unit test of `categorize` of `doc/library_doc_panel.tsx`
Display of namespaces on doc pages
Currently we flatten symbols in namespaces on the doc symbol index page. This was mainly a carry over from docland, where we didn't have a symbol nav on the left of the page.
The target state would be not to flatten symbols on the index, but nest namespace symbols on the left nav, which would allow users to expand a namespace as appropriate.
Enable using doc_components as a library or standalone tool
Use Case
I'm writing a library that I want to publish to deno.land because Deno's great, and I get free API doc web pages there. But, I'm not super familiar with JSDoc, or Deno's extensions(?) to that format, so I'd love to be able to preview what my docs will look like on deno.land during development.
Currently, the closest I can do locally is deno doc myMod.ts
to see what docs get generated, but that doesn't show me how some web-only things will work:
- How do my code blocks get formatted?
- How/Whether my
{@link terms}
work - Did I use (Deno's) JSDoc sytnax properly?
If I want to see the docs rendered, I've got to publish a build to deno.land/x/, see my bugs, patch, and repeat.
Problem(s)
I was hoping to make a quick tool that would use doc_components and let me see its output locally.
However, since doc_components uses import maps, I must mirror those import maps in my tool. And there seems to currently be a bug in deno install
that makes import maps not work for installed codebases, which means I won't be able to publish my tool and have others easily use it.
Request
My main goal is to be able to generate docs locally that look like they'll look on deno.land. So the straightforward options are:
- The Deno (Docs?) team implements such a tool. (yay, easy for me!) :)
- Update this library to let other folks reuse it to write such a tool.
- Fix the bug with
deno install
ing import maps.
Add examples of properties in class with decorators
remove duplicated code and other clean ups
- Some of the functions in here should be refactored to a common space
- module_index module_path_index and module_symbol_index are essentially the same component we were iterating on. We should drop the two lovers and refactor to clean up whatever is left.
- publish a tag instead of going off a git commit.
Internal server error on showcase
I got this error:
Listening on: http://0.0.0.0:3100/
[uncaught application error]: TypeError - Cannot read properties of undefined (reading 'toLowerCase')
request: { url: "http://0.0.0.0:3100/", method: "GET", hasBody: false }
response: { status: 404, type: undefined, hasBody: false, writable: true }
at file:///Users/hash/Documents/GitHub/doc_components/doc.ts:63:44
at Array.find (<anonymous>)
at getIndex (file:///Users/hash/Documents/GitHub/doc_components/doc.ts:63:24)
at ModulePathIndexPanel (file:///Users/hash/Documents/GitHub/doc_components/module_path_index_panel.tsx:152:23)
at renderFunctionalComponent (https://deno.land/x/[email protected]/core.ts:160:18)
at _render (https://deno.land/x/[email protected]/core.ts:134:70)
at https://deno.land/x/[email protected]/core.ts:46:17
at Array.forEach (<anonymous>)
at appendChildren (https://deno.land/x/[email protected]/core.ts:41:12)
at Object.h (https://deno.land/x/[email protected]/core.ts:286:3)
[error] TypeError: Cannot read properties of undefined (reading 'toLowerCase')
at file:///Users/hash/Documents/GitHub/doc_components/doc.ts:63:44
at Array.find (<anonymous>)
at getIndex (file:///Users/hash/Documents/GitHub/doc_components/doc.ts:63:24)
at ModulePathIndexPanel (file:///Users/hash/Documents/GitHub/doc_components/module_path_index_panel.tsx:152:23)
at renderFunctionalComponent (https://deno.land/x/[email protected]/core.ts:160:18)
at _render (https://deno.land/x/[email protected]/core.ts:134:70)
at https://deno.land/x/[email protected]/core.ts:46:17
at Array.forEach (<anonymous>)
at appendChildren (https://deno.land/x/[email protected]/core.ts:41:12)
at Object.h (https://deno.land/x/[email protected]/core.ts:286:3)
simply change to file?.toLowerCase()
here works, but might need some typing fix.
https://github.com/denoland/doc_components/blob/main/doc.ts#L63
Index Page should only show 1 deep and nest
The module index (https://deno-doc-components.deno.dev/#moduleindex) should only show one level deep and nest.
Selectable function signature should be selectable
The selectable signature shouldn't be selectable anymore. This makes it difficult for a user to select other parts of the signature if they want and once symbol linking is enabled, people may very well want to navigate to other symbols from the signature instead of having to scroll down to the expansion.
Inferring public properties from a class's constructor is not supported.
Inferring public properties from a class's constructor is not supported.
input :
export class TrieNode {
constructor(
public wordCount: number = 0,
public prefixCount: number = 0,
public readonly children = new Map<string, TrieNode>(),
) {}
}
output:
export declare class TrieNode {
wordCount: number;
prefixCount: number;
readonly children: Map<string, TrieNode>;
constructor(wordCount?: number, prefixCount?: number, children?: Map<string, TrieNode>);
}
https://deno.land/x/[email protected]/implement-trie-ii-prefix-tree/TrieNode.ts?source
[bug] ui: missing space after `readonly` in doc view
Hey Deno fam, just a small UI issue I came across recently on deno.land. When viewing the doc view of a module, like dax
for example, the readonly
tag has no spacing between it and the variable name in question.
Here's a screenshot to highlight what I'm talking about, in case the link above does not show it:
Thanks!
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.