gcanti / docs-ts Goto Github PK

I expected the Why section to explain the advantages of docs-ts over alternatives like typedoc.

Why would one choose docs-ts over typedoc?

Thanks

Do you want to request a feature or report a bug?

Feature

What is the current behavior?

In _config.yml the aux_links/github field is automatically set with package.json's homepage value which can be different from repository url

If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://codesandbox.io/ or similar.

What is the expected behavior?

Another field github in docs-ts.json field that will be used as aux_links/github link.

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?

0.6.2

Do you want to request a feature or report a bug?

It seems to be a bug

What is the current behavior?

Prettier ^2.0.0 is required as peer dependency and it is used in runtime code.

If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://codesandbox.io/ or similar.

Prettier cannot be upgraded to v3 in a project that uses docs-ts as dependency:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR! 
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/prettier
npm ERR!   dev prettier@"3.0.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer prettier@"^2.0.0" from [email protected]
npm ERR! node_modules/docs-ts
npm ERR!   dev docs-ts@"0.8.0" from the root project
npm ERR! 
npm ERR! Conflicting peer dependency: [email protected]
npm ERR! node_modules/prettier
npm ERR!   peer prettier@"^2.0.0" from [email protected]
npm ERR!   node_modules/docs-ts
npm ERR!     dev docs-ts@"0.8.0" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

What is the expected behavior?

Users should be able to upgrade Prettier to v3 (or further versions) and docs-ts should still work.

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?

• docs-ts v0.8.0
• any browser
• any OS

Do you want to request a feature or report a bug?
Don't think it's a bug, but it's unclear how to proceed with the usage of docs-ts for my project due to an error

What is the current behavior?
I am unable to generate my docs due to the following error:

/home/cdimitroulas/code/cdimitroulas/smart-types-ts/node_modules/ts-node/src/index.ts:513
    return new TSError(diagnosticText, diagnosticCodes)
           ^
TSError: ⨯ Unable to compile TypeScript:
docs/examples/src-array-arrayWithLength.ts-function-mkArrayWithLength-0.ts(2,1): error TS2349: This expression is not callable.
  Type 'String' has no call signatures.

    at createTSError (/home/cdimitroulas/code/cdimitroulas/smart-types-ts/node_modules/ts-node/src/index.ts:513:12)
    at reportTSError (/home/cdimitroulas/code/cdimitroulas/smart-types-ts/node_modules/ts-node/src/index.ts:517:19)
    at getOutput (/home/cdimitroulas/code/cdimitroulas/smart-types-ts/node_modules/ts-node/src/index.ts:752:36)
    at Object.compile (/home/cdimitroulas/code/cdimitroulas/smart-types-ts/node_modules/ts-node/src/index.ts:968:32)
    at Module.m._compile (/home/cdimitroulas/code/cdimitroulas/smart-types-ts/node_modules/ts-node/src/index.ts:1056:42)
    at Module._extensions..js (internal/modules/cjs/loader.js:789:10)
    at Object.require.extensions.(anonymous function) [as .ts] (/home/cdimitroulas/code/cdimitroulas/smart-types-ts/node_modules/ts-node/src/index.ts:1059:12)
    at Module.load (internal/modules/cjs/loader.js:653:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:593:12)
    at Function.Module._load (internal/modules/cjs/loader.js:585:3)

My repository can be found at https://github.com/cdimitroulas/smart-types-ts - I would appreciate any guidance on what I have done wrong in setting up docs-ts 🙏 I would like to also say thanks for all your hard-work on the fp-ts ecosystem - using fp-ts has really changed my way of programming for the better so I am very grateful!

What is the expected behavior?
I was hoping to generate my first docs with docs-ts for my project 😄

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?
[email protected]

Just as @since is enforced, it'd be nice if we could also enforce JSDoc descriptions and @example tags. Personally I'd consider the latter two more important than that which is already enforced.

You need to run yarn add -D @types/node on your project if you want to make use of the assert module in the @example section. Otherwise you get an error when generating the docs.

This should be either mentioned in the readme or included as a (peer)dependency?

docs-ts is unable to locate the config despite it being in the root directory of my project.
I just want to set enforceVersion to false and live happily ever after.
My docs-ts.json:

{
	"enforceVersion": false
}

CLI output on npx docs-ts:

...
1 modules found
Parsing files...
missing documentation in src/index.ts module
missing @since tag in src/index.ts#foo documentation
missing @since tag in src/index.ts#bar documentation
...

Do you want to request a feature or report a bug?
Feature: Forward options to ts-morph.

What is the current behavior?
docs-ts provides {"strict": true} as configuration to the ts-morph project.

Use case
I want to provide a non-default tsconfig.json to ts-morph, but this is not possible, because docs-ts provides a fixed config. ts-morph itself would allow a `different configfile name.

This makes docs-ts hard to use, in case the own project uses a tsconfig.json which isn't compatible with node (my concrete case is, that I can't find a module option, that satisfies webpack's ts-loader and docs-ts and also ts-loader is really unhappy, if I tell it to use a different tsconfig.json).

What is the expected behavior?
Add an optional entry "ts-morph" to docs-ts.json, which is forwarded to ts-morph.

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?
All. (Using 0.6.10)

I'm willing to implement this, if it has the chance to be merged.

Oh: And btw: @gcanti: I love your typescript work. Thank you so much. :-)

via fp-ts#1218

Where TS is:

<A, B>(f: (a: A) => IO<B>) => (ma: IO<A>) => IO<B>

HM would be:

(a -> IO b) -> IO a -> IO b

I think it'd be great if this generated type signatures in both styles with a client-side toggle to globally switch between them, defaulting to TS.

Another small one:

Should we omit the .ts in the generated module names in the sidebar?

Feature.

Jekyll is pretty dated at this point. Vitepress provides more modern solution that is also much much more aesthetically pleasing. Given that the forks fp-ts/core and fp-ts/data are using vitest anyway vitepress seems like a logical direction to go in. https://vitepress.vuejs.org/

Repro:

1. Clone fp-ts-std (and checkout 5870c44).
2. Add a docs-ts.json file with the following contents:

{
  "enforceExamples": true
}

3. Run yarn docs (alias for docs-ts).
4. The output will be as follows:

14/03/2021 | 17:39:39 | DEBUG | Project name detected: fp-ts-std
14/03/2021 | 17:39:39 | DEBUG | Checking for configuration file...
14/03/2021 | 17:39:39 | INFO | Found configuration file
14/03/2021 | 17:39:39 | DEBUG | Parsing configuration file found at: /home/sam/dev/fp-ts-std/docs-ts.json
14/03/2021 | 17:39:39 | INFO | Found 17 modules
14/03/2021 | 17:39:39 | DEBUG | Parsing files...
Missing examples in src/Array.ts#Array documentation
Missing examples in src/Boolean.ts#Boolean documentation
Missing examples in src/Date.ts#Date documentation
Missing examples in src/Debug.ts#Debug documentation
Missing examples in src/Either.ts#Either documentation
Missing examples in src/Env.ts#Env documentation
Missing examples in src/Function.ts#Function documentation
Missing examples in src/index.ts#index documentation
Missing examples in src/IO.ts#IO documentation
Missing examples in src/JSON.ts#JSON documentation
Missing examples in src/Number.ts#Number documentation
Missing examples in src/Option.ts#Option documentation
Missing examples in src/Record.ts#Record documentation
Missing examples in src/String.ts#String documentation
Missing examples in src/Task.ts#Task documentation
Missing examples in src/URL.ts#URL documentation
Missing examples in src/URLSearchParams.ts#URLSearchParams documentation
error Command failed with exit code 1.

I have examples for I think absolutely everything, and they do successfully make it into the generated documentation.

Small modules which could be easier to verify would be Debug, IO, and Task.

Using export { f } from 'm' syntax with the usual accompanying JSDoc fails with a "missing f documentation" error.

After installing docs-ts via yarn add docs-ts I run yarn docs-ts and get this error:

Error: Cannot find module 'prettier'

I have to manually yarn add prettier to make it work.

Is prettier maybe a dependency and not a dev dependency of docs-ts?

what about it?

I've been trying to see how to update fp-ts-rxjs with the latest version of rxjs, however as has been noted before, the docs that are generated afterwards have the type any in place of the expected Observable. I have found that using a version of docs-ts with the latest ts-morph to generate the docs solves the issue.

When Observable is imported from rxjs@^7.0, a function such as the following

export const ap: <A>(fa: Observable<A>) => <B>(fab: Observable<(a: A) => B>) => Observable<B> = fa => fab =>
  combineLatest([fab, fa]).pipe(rxMap(([f, a]) => f(a)))

has its generated documented type set as

export declare const ap: <A>(fa: any) => <B>(fab: any) => any

When docs-ts uses the latest morph-ts, we get the correct result:

export declare const ap: <A>(fa: Observable<A>) => <B>(fab: Observable<(a: A) => B>) => Observable<B>

Note that the documentation is generated correctly with the latest release of docs-ts and rxjs@^6.0. I'm not too sure exactly what changes to ts-morph fix the issue or exactly how the bug is caused with the current version of docs-ts.

Unfortunately I introduced a regression bug with my previous PR.

There's a semicolon missing in those lines: https://github.com/gcanti/docs-ts/blob/master/src/Core.ts#L250-L251

That currently makes my-package/lib/foo and my-package/foo/bar imports to fail.

However, the problem is not solved by just adding the semicolons. I'll prepare a PR and add more info in there.

I believe the current output of the signatures could be improved to help readability.

I'm willing to work on these improvements, but first I'd like to see if this is something that would make sense to add.

So far I've found two cases that I'd like to improve.

NOTE: the suggestions are based on the goal of having the signature snippets being valid TS. See #13 (comment)

Only types in the signature

Currently the generated signature could be very verbose, as are TypeScript types. But it also includes part of the body of the function on it.

Eg. The following function from a RemoteData module that I use at work:

export const toEither = <E = unknown>(
  onNone: (status: 'idle' | 'loading') => E,
  onFailure: (err: ErrorAsync) => E
) => <A = unknown>(rda: RemoteData<A>): Either.Either<E, A> =>
  fold<A, Either.Either<E, A>>({
    idle: () => Either.left(onNone('idle')),
    loading: () => Either.left(onNone('loading')),
    success: Either.right,
    failure: flow(Either.left, Either.mapLeft(onFailure)),
  })(rda);

Produces this in the signature section.

export const toEither = <E = unknown>(
  onNone: (status: 'idle' | 'loading') => E,
  onFailure: (err: ErrorAsync) => E
) => <A = unknown>(rda: RemoteData<A>): Either<E, A> =>
  fold<A, Either<E, A>>({
    idle: () => left(onNone('idle')),
    loading: () => ...

Instead, only the types could be generated to show the signature.

declare const toEither: <E = unknown>(
  onNone: (status: 'idle' | 'loading') => E,
  onFailure: (err: ErrorAsync) => E
) => <A = unknown>(rda: RemoteData<A>) => Either<E, A>;

Overloaded functions

For the same RemoteData function, the filterOrElse function (from MonadThrow) produces this overloaded signature:

{ <E, A, B>(refinement: Refinement<A, B>, onFalse: (a: A) => E): (ma: RemoteData<A>) => RemoteData<B>; <E, A>(predicate: Predicate<A>, onFalse: (a: A) => E): (ma: RemoteData<A>) => RemoteData<A>; }

It's not very friendly to read the whole signature in one line like that.

Interface could be used for function overloading:

interface filterOrElse {
  <E, A, B>(refinement: Refinement<A, B>, onFalse: (a: A) => E): (
    ma: RemoteData<A>
  ) => RemoteData<B>;

  <E, A>(predicate: Predicate<A>, onFalse: (a: A) => E): (
    ma: RemoteData<A>
  ) => RemoteData<A>;
}

Do you want to request a feature or report a bug?
bug

What is the current behavior?
I annotate my private method with a JSDoc containing @internal or @ignore, and the documentation is generated

If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://codesandbox.io/ or similar.

/**
 * Description
 *
 * @example
 * const a = 3
 * 
 * @category Animal
 */
export default class Dog {
  public bark() {}
  /** @internal */
  private scratch() {}
}

What is the expected behavior?
I expect the documentation to not be generated

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?
v0.6.9, first time I use it.

Do you want to request a feature or report a bug?
I want to report a bug

What is the current behavior?
When I have documented getters in my class and try to generate documentation, they are skipped from the final md file

If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://codesandbox.io/ or similar.
Minimal reproducing code: https://codesandbox.io/s/mystifying-dewdney-qi2drx?file=/src/index.ts . Final md file contains description of the class itself, and function isRunning, but getter running is missed

What is the expected behavior?
Getters should be visible in final documentaion md file alongside with functions and properties

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?
docs-ts version 0.7.0 not sure if it worked earlier. OS: Arch Linux 64bit.

What is the current behavior?

When modules only have export from statements it results in an empty ToC.

Eg. the following src/http/index.ts file:

export * from './http'
export * from './utils'

Would result in this generated doc:

---
title: http/index.ts
nav_order: 1
parent: Modules
---

## index overview

Some overview

---

<h2 class="text-delta">Table of contents</h2>

---

What is the expected behavior?

I'm not sure what should be the expected behaviour 🤔

One idea is to remove the ToC title, since there's no ToC. But that would still result in an empty document.

We could show all the exports from the module instead.

Or add a new section that mentions all the exported modules. hadoc does this, module exports show up in the docs as a reference to the module (see Data.Map documentation)

module Data.Map
    ( module Data.Map.Lazy
    -- ...
    ) where

module Data.Map
    ( module Data.Map.Lazy
    -- ...
    ) where

Which versions of docs-ts?

I'm using v0.6.4

Currently docs-ts uses prettier to format markdown before writing out the docs.

The used options are:

const prettierOptions: prettier.Options = {
  parser: 'markdown',
  semi: false,
  singleQuote: true,
  printWidth: 120
}

The code blocks in Jekyll seem to work without horizontal scrolling only if lines don't exceed a 80 characters limit.

Is this intended behavior?

If not, I'd suggest one of those options:

• Configure Jekyll to use 120 characters as limit (don't know if this is possible)
• Configure Prettier to use 80 character limit

Or, and this Is what I would suggest:

• Don't format at all inside docs-ts and encourage the user to use prettier-plugin-jsdoc. This is a much better editing experience. You have more control about the format, plus in the end the actual source file has the same formatting as the docs.

What do you think?

I've hit a bug in the parser, where ts-morph throws TypeError: Cannot read property 'flags' of undefined.
I'm unsure why this is the case in my project in particular, but it's not an usually using something like export * as namespace from './file' results in some errors.

I make the assumption that because ts-morph is just a wrapper around the typescript compiler, that ts-morph hasn't been coded to handle newer syntax. If we used the original typescript compiler, we're less likely to get an issue like this. If we do, it'll be easier to fix as it'd be a problem with our code, not the compiler's code.

Why use ts-morph over tsc? Do we gain any benefits using one over the other?

Do you want to request a feature or report a bug?

feature

What is the current behavior?

I have a library I am trying to document using docs-ts, because it is a library of io-ts codecs. I have written examples for each of the core codecs and suddenly encounter an issue where npx docs-ts fails like that:

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /Users/eve/docmaps/packages/ts-sdk/docs/examples/index.ts
    at new NodeError (node:internal/errors:399:5)
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:79:11)
    at defaultGetFormat (node:internal/modules/esm/get_format:121:38)
    [ ... omitted ... ]
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

It seems like docs-ts is doing some awesome footwork to prove that my examples actually compile or type check anyway. However I haven't found docs or other issues that reference this behavior. Could we get an explainer on this, or info in the docs? I need to write examples, auto checking is optional feature for me so I would also be happy turning it off if there is need.

Thanks very much!

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?

NodeJS 18.14.0, macos 13.3, docs-ts 0.7.2

I've been trying to put together a PR for fp-ts documentation. I would like to take advantage of the Just-the-Docs theme and its sidebar, but what's missing is a place to write documentation because, at the moment, docs-ts deletes all files in /docs (with small exceptions), which makes this difficult. I would suggest to only delete *.ts.md files in docs.

I understand that you have already written several pieces of documentation in fp-ts’s root folder as markdown files. However, due to technical restrictions from GitHub Pages, it would be much easier to work with documentation if everything were in the /docs folder (also the logo, for example, which currently can't really be referenced from docs).

I would like to achieve something like this, where the sidebar provides some high-level entry points (there would be more, but not many more):

What would further simplify this is if the generated module files would be placed in /docs/modules/*.ts.md; or even /docs/modules-gen or something with a disclamer that these are generated files. (They could use Jekyll’s permalink frontmatter to state that they are really found at /modules.)

How do you see this? The way you have set out to document your libraries with docs-ts seems to be focused on generated API documentation. This is already a great win, definitely! But I would like to argue that your libraries could greatly benefit from more comprehensive documentation for different levels of knowledge, similar to what you're doing with your recent dev.to articles. (I'm thinking of my co-workers who often struggle to find their way around.) If you would be open to changing this, I think that the README.md files would change as well, providing more information on how to develop the library and contribute and moving user-facing documentation into /docs.

Currently a rule such as enforceExamples is enforced against everything indiscriminately. This poses a challenge if I want to enable it in a repo like fp-ts where there's for example an index module. It also means I can't enable it for all new code in a repo going forward from any given point whilst ignoring the preexisting failures, as one might do for a linter or an upgrade from plain JS to TS.

In an ideal world docs-ts would allow you to specify exclusions or otherwise ignore certain files or pieces of code.

Currently, we only mention in the README:

"...the generated output of docs-ts can be used as a publishing source for your repository's documentation on GitHub".

Workable Recipe

Maybe it would be nice to have a way to review the rendered docs locally.

For me the following worked. And as a non-ruby-ist it took me a while to figure out:

1. Put a Gemfile with this content into the docs folder:

source "https://rubygems.org"

gem "github-pages", "~> 212", :group => :jekyll_plugins

2. Run cd docs; bundle exec jekyll serve

Include somehow in docs-ts?

Would it make sense to include the Gemfile in the generated output and then add a section to the readme that explains how to run jekyll on it?
Or maybe you have other suggestions here.

Hot reload

Furthermore, I tried to setup a complete hot reloading workflow, and this worked:

If you run

cd docs; bundle exec jekyll serve --livereload

and in parallel:

while inotifywait -e close_write src; do yarn docs; done

The docs are refreshed in the browser on every file save. However, maybe only suitable for small projects, as all the files are processed on each trigger. So this might another topic.

I was looking at gcanti/fp-ts#1337 and noticed that in place of a Nullable<A> as a return type, the docs currently show:

(Source: https://gcanti.github.io/fp-ts/modules/Option.ts.html#tonullable)

I'm not suggesting that we add Nullable, since this is a trivial type helper; however, I think there might be an issue with the documentation generator omitting null and undefined. This appears to affect the generated markdown for both toUndefined and toNullable, but there might be others.

Notice that the signatures in the module do contain null and undefined.

(Source: https://github.com/gcanti/fp-ts/blob/master/src/Option.ts#L434)

Do you want to request a feature or report a bug?
A bug

What is the current behavior?
docs-ts produces output paths such as docs\modules\.md for every module on Windows 10

If the current behavior is a bug, please provide the steps to reproduce and if possible a minimal demo of the problem via https://codesandbox.io/ or similar.
run docs-ts on windows

What is the expected behavior?
output path should mirror the module source filename.

Which versions of docs-ts, and which browser and OS are affected by this issue? Did this work in previous versions of docs-ts?
🤷‍♂