search

esdmr / template

NodeJS template with Linting, Testing, Typescript and CI support
https://esdmr.github.io/template/
MIT License
0 stars 0 forks source link

Better documentation interface #52

Open esdmr opened 3 years ago

esdmr commented 3 years ago

Suggestion

Replace api-extractor and api-documenter for a better alternative. Also perhaps remove Jekyll.

Benefit

By switching to TypeDoc (and ditching Jekyll, yay) the documentation will look better and the search will be scoped to every version.

This suggestion is unique

You may use the editor below to elaborate further.

The subpath exports are not regarded. Probably use typedoc-plugin-external-module-name to fix that.

The documentation will no longer be written in Markdown. It is possible to revert this by using typedoc-plugin-markdown, however it does not look as good as the HTML. Additionally it would need to be converted using Jekyll (as it is currently done. Ugh, what was I thinking?).

Unfortunately we may not be able to use KaTeX. This needs more investigation. But I would doubt anyone needs to write equations in documentation.

esdmr commented 3 years ago

Oh, wow. I now realize this requires tremendous effort to integrate everything together. Plus the possible future effort to convert all fish scripts to JavaScript, the proposal is almost too much. I will try anyway, but this may get postponed indefinitely.

The current steps are as follows:

  1. Using the generated files under build directory, and the sub-path exports in package.json, construct a list of entry points available to the public. Note that a sub-path export could have no exported file assigned. That is a mistake to be reported.
  2. Those entry points point to the build directory. Use tsconfig.json to find the correct source file under the src directory. Note that a built file could have no source file, or have missing declaration files. That is a mistake to be reported.
  3. Once we found the source files exported to the public, we will inform the typedoc-plugin-external-module-name that these files should be aliased. Then we will call typedoc to generate the documentation. Note that the aforementioned plugin has a compatibility issue with newer versions of typedoc. Either the plugin should be rewritten to accommodate for the breaking change introduced, or forfeit the access to the recent versions of typedoc for an indefinite length of time awaiting the update. ~Note that the last supported version of typedoc does not fully support aggregate exports (reexports).~
  4. Modify the documentation to remove Ruby and Jekyll. My favourite step, Preceded only by the most burdensome tasks.

Edit: I say the first two items as if I have not already hacked together the rest of the codebase. lol

Edit: The only project requiring aggregate exports, esdmr/assert, will be archived in the near future.