denoland / doc_components

A set of components for rendering deno_doc doc nodes

deno_doc_components

A set of components used to render deno_doc DocNodes.

Showcase

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.

Usage

Services

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.

href()

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.

lookupSymbolHref()

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

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 Issues

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.

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

const tree = lowlight.highlight(lang, htmlEntities.decode(code), {

This causes error in the following page:

https://deno.land/[email protected]/testing/chai_example.ts

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.

Doc View Nav should render deprecated symbols differently

We should have some visual indication in the nav that a symbol is deprecated if it has the JSDoc deprecated tag. Maybe strikethrough on the name?

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.

Code block spacing with private

Missing the private keyword spacing.

Add examples of properties in class with decorators

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 Component should collapse table in mobile

The Module Doc component collapses the two column when in mobile, Index page should as well.

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.

Add unit test of `categorize` of `doc/library_doc_panel.tsx`

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(&quot;import * as mod from &quot;https://deno.land/[email protected]/fmt/colors.ts&quot;;
&quot;);">

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.

display multiple symbol kinds as one symbol in module doc

Follow up to #50

[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!

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.

bug: doc index looks kind of janky

https://deno.land/[email protected]/encoding

Root module should not be "expandable"

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>(),
    ) {}
}

https://www.typescriptlang.org/play?#code/KYDwDg9gTgLgBAYwDYEMDOa4BUoEtgByEAJsHAN4CwAUHHYhAHZoxQCuCM0AFDff3DBsARklwI4Ad2jEAwhDaMYALjiM2AW2HAocALxwADABo+AukNHjBUYADNcIeYpVrN23QZNnzlsRNsUYiYkAE9EAAtcJGJbRn01YEk4AFkUMAAeFjxGAHNjbDxCEmAAPm4ASlNaegqKAF8aRuogA

output:

export declare class TrieNode {
    wordCount: number;
    prefixCount: number;
    readonly children: Map<string, TrieNode>;
    constructor(wordCount?: number, prefixCount?: number, children?: Map<string, TrieNode>);
}

https://doc.deno.land/https://deno.land/x/[email protected]/implement-trie-ii-prefix-tree/TrieNode.ts/~/TrieNode

https://deno.land/x/[email protected]/implement-trie-ii-prefix-tree/TrieNode.ts?source

default exports missing from module doc pages

For example: https://deno.land/x/[email protected]/mod.ts

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 installing import maps.

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:

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.