Coder Social home page Coder Social logo

doc_components's Introduction

deno_doc_components

deno doc Build Status - Cirrus Twitter handle Discord Chat

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 People

Contributors

bartlomieju avatar bodograumann avatar crowlkats avatar deer avatar hashrock avatar jespertheend avatar kitsonk avatar kt3k avatar lambtron avatar lino-levan avatar magurotuna avatar marvinhagemeister avatar meszarosdezso avatar sigmasd avatar xnuk avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

doc_components's Issues

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.

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

Screen Shot 2022-08-14 at 11 39 06 AM

Thanks!

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
image

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.

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
copy button

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 &quot;).

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

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

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.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

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

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.