denoland / doc_components Goto Github PK

Follow up to #50

@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.

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.

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.

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.

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

• 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.

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.

The below lowlight.highlight call seems throwing error if the language is unknown.

This causes error in the following page:

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

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:

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

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?

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

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

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.

Missing the private keyword spacing.

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!

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

The module index (https://deno-doc-components.deno.dev/#moduleindex) should only show one level deep and nest.