citkane / typedoc-theme-yaf Goto Github PK

A fresh, opinionated and standalone front-end documentation application consuming Typedoc generated data.

Home Page: https://citkane.github.io/typedoc-theme-yaf/dev/

License: MIT License

CSS 0.82% JavaScript 1.05% TypeScript 79.83% SCSS 17.47% HTML 0.83%

documentation documentation-tool javascript theme typedoc typedoc-plugin typedoc-theme typescript

typedoc-theme-yaf's Introduction

⚡ This theme is pegged at Typedoc v0.23 due to breaking API changes in v0.24

typedoc-theme-yaf

A theme that optimises deep project exploration, graphical clarity and a fluid end user experience.

Live Example

Usage

The documentation content and navigation is fully cross-linked with n-depth expanding drawers. During user navigation events, contexts are automatically expanded and highlighted in both directions, so there exists a singular DRY visual mechanism for the reader to keep their place within.

Versioning

This theme automatically creates a semantically versioned history of your documentation.
For more information, see typedoc-plugin-versions, which includes options and examples of how to set up a Github CID for your documentation.

Installation

npm i -D typedoc-theme-yaf

Once installed, adjust your TypeDoc options to reflect:

{
	"plugin": ["typedoc-theme-yaf"],
	"theme": "yaf"
}

Proceed with building your documentation.

Note: the index.html output for the documentation build will be a SPA entry point, so very little will happen if you open it with your browser locally. You will have to serve it with a server application of your choice, eg. the VS-Code Live Server plugin.

Front-end Strategy

The frontend decouples itself from the default TypeDoc theme .html fragment strategy and creates a single page application (SPA) which consumes .json data fragments.

This facilitates a user experience where place-keeping while reading and navigating is maintained across document pages, page reloads and browser sessions.

Options to show or hide complexity, such as private or inherited items, are left to the end user. Toggle buttons are contextually placed and easy to both understand and use.

The visual length of content is handily compressed with folding "drawers".
The open/close state of these as well as the page scroll position is persisted, so the end user spends less time finding items on long pages and more time reading them.

The SPA is built with zero dependencies using Web Components.

Back-end Strategy

The backend takes as input the default TypeDoc ProjectReflection and JSONOutput.ProjectReflection and outputs a collection of .json data files for consumption by the frontend.

The theme does not (majorly) interfere with the default TypeDoc data construction flow, but rather post-serialises the standard Typedoc output into it's own needs.

Contribution and Development

Please report in the issues if something breaks when you render your project with this theme in such a way that it is not usable (ie. breaking issues only please).

If you spot a gremlin, or want to suggest an enhancement, please use the Github discussion section.

If you want to get involved in the code, please clone the repo and submit your pull requests.

Hot Development

You can spin up a local hot development instance by running npx hot-dev from your terminal. This is already installed as a theme dev-dependency.
Before the first run only, do npm i && npm run build.

Roadmap

Short Term

~~Implement search functionality~~ ✅
~~Implement document versioning~~ ✅
~~Implement reflection reference linkages across mono-repo workspaces~~ ✅
~~Write meaningful tests...~~ ✅

Medium Term

Implement tabbed bookmarks
Implement end user sticky notes (using local storage)
Migrate code view from external links to local rendering. Enable bookmarks, notes for same.
Support diagrams in MarkDown
Main navigation menu extension, eg. .md defined tutorials and documentation with hierarchical chapters.
Unit testing

Long term

Either or;
- collaborate with TypeDoc to normalise it's default JSON output to theme compatibility,
- purpose build a TSDoc document parser back-end and migrate this theme to be a standalone documentation product.

typedoc-theme-yaf's People

Contributors

Stargazers

Watchers

typedoc-theme-yaf's Issues

Rendering issues

As it can be seen in the image, the font of the link to the source file is thin and (in my opinion) hard to read, with the underline being an aggravating factor.

The same font seems to be used for the return type, but there readability is not that bad.

I suggest a thinker font, and possibly to remove the underline.

Also, in the parameters table, the flag (rest) is not vertically aligned with the raw.

Coalesce the return type with the @returns tag

I have the following input sequence:

  /**
   * @summary Getter to obtain the underlying `console` object.
   *
   * @returns The console object used by the logger.
   */
  get console (): Console {
    return this._console
  }

It is rendered like this:

Although I cannot say it is incorrect, having two Returns is not optimal

Would it be possible to render the content of the @returns right after the return type, or, if short, even on the same line?

This would also be more consistent with rendering for the function parameters, where the type and the @param tag are on a single line.

Links to absolute paths?

I tried this theme (0.0.3), and it generally looked nice, but I have a problem when deploying it to GitHub Pages.

The site was generated on my local machine and it took me some time to discover that there are several symbolic links pointing to absolute paths, which fail when publishing on the GitHub Pages servers:

ilg@wksi docs % find . -type l -exec ls -l '{}' ';'
lrwxr-xr-x  1 ilg  staff  83 Feb 18 21:54 ./stable -> /Users/ilg/My Files/WKS Projects/xpack.github/npm-modules/logger-ts.git/docs/v6.0.0
lrwxr-xr-x  1 ilg  staff  83 Feb 18 21:54 ./v6.0 -> /Users/ilg/My Files/WKS Projects/xpack.github/npm-modules/logger-ts.git/docs/v6.0.0
lrwxr-xr-x  1 ilg  staff  83 Feb 18 21:54 ./dev -> /Users/ilg/My Files/WKS Projects/xpack.github/npm-modules/logger-ts.git/docs/v6.0.0
ilg@wksi docs %

Is there any reason for not using relative paths in these symbolic links?

Does not work with the latest typedoc

After the deps update I got an error:

$ npm run build:docs

> [email protected] build:docs
> typedoc

[info] Loaded plugin typedoc-plugin-missing-exports
Loaded plugin typedoc-plugin-versions
[info] Loaded plugin typedoc-theme-yaf
[warning] TypeDoc has been loaded multiple times. This is commonly caused by plugins which have their own installation of TypeDoc. The loaded paths are:
        /projects/test/node_modules/typedoc
        /projects/test/node_modules/typedoc-theme-yaf/node_modules/typedoc
TypeDoc exiting with unexpected error:
TypeError [ERR_INVALID_ARG_TYPE]: The "from" argument must be of type string. Received undefined
    at new NodeError (node:internal/errors:399:5)
    at validateString (node:internal/validators:163:11)
    at relative (node:path:1191:5)
    at ReflectionSymbolId.toObject (/projects/test/node_modules/typedoc/dist/lib/models/reflections/ReflectionSymbolId.js:49:66)
    at /projects/test/node_modules/typedoc/dist/lib/models/reflections/project.js:214:35
    at Map.forEach (<anonymous>)
    at ProjectReflection.toObject (/projects/test/node_modules/typedoc/dist/lib/models/reflections/project.js:213:40)
    at Serializer.toObject (/projects/test/node_modules/typedoc/dist/lib/serialization/serializer.js:21:69)
    at Renderer.prepareYafTheme (/projects/test/node_modules/typedoc-theme-yaf/src/backend/YafTheme.js:93:59)
    at triggerEvents (/projects/test/node_modules/typedoc/dist/lib/utils/events.js:191:43) {
  code: 'ERR_INVALID_ARG_TYPE'
}

Looks like wrong inheritance from the default theme.
TypeStrong/typedoc#1786
TypeStrong/typedoc#1741 (comment)

dependencies in package.json:

"typedoc": "^0.24.8",
"typedoc-plugin-missing-exports": "^2.0.0",
"typedoc-theme-hierarchy": "^3.2.0",
"typedoc-theme-yaf": "^0.0.4",
"typescript": "^5.1.3"

typedoc.json:

{
    "entryPoints": [
        "./src/index.ts",
    ],
    "exclude": ["./src/test.ts"],
    "out": "docs",
    "includes": "./src",
    "readme": "./readme.md",
    "sort": ["static-first", "alphabetical"],
    "disableSources": false,
    "plugin": ["typedoc-plugin-missing-exports", "typedoc-theme-yaf"],
	"theme": "yaf"
}

Accessors do not have the link to the source file

Here is a screen capture of an accessor:

The same content, but with the default theme:

As it can be seen, the source line information, present with the default theme, is missing with the yaf theme.

Absolute symlinks within generated docs

I really like the looks of the output from typedoc-theme-yaf. However, because it uses typedoc-plugin-versions under the covers, the symbolic links that get created are absolute ones -- relative to the directory hierarchy on my development environment.

That makes it basically impossible to transport the generated docs directory to some static webserver, or publish it as GitHub Pages.

Is there any way that you (or the maintainers if any for typedoc-plugin-versions) could make relative symbolic links possible?

Inline `@link` tags don't resolve correctly when used within `@params` and some `@see` tags.

The above called link, which is written in my tsdoc as {@link call called}, resolves to /docs/dev/405, which leads (ironically) to a 404 error.

Elsewhere within the same class:

This called link (also written in tsdoc as {@link call called}) correctly points to /docs/dev/?page=Function.call.

Most examples I have found of inline @link tags not resolving correctly seem to be witin @param tags, For example, this resolves perfectly:

    /**
     * The endpoint at which the {@link Npc NPC procedure} is available to be {@link call called} or {@link notify notified}.
     */

However, this completely fails, none of the inline @link tags resolve correctly:

    /**
     * @param {T} callback The underlying {@link Callback callback} function which will be {@link call called} by clients.
     */

The problem also seems to affect @see tags on functions/class methods.