search

emmanueltouzery / prelude-ts

Functional programming, immutable collections and FP constructs for typescript and javascript
ISC License
377 stars 21 forks source link

Retire sed #42

Open aleksei-berezkin opened 4 years ago

aleksei-berezkin commented 4 years ago

Hi. Started here from just replacing sed with couple of scripts, without moving to any other script. The result apidoc === what was before, checked it with per-file diff.

emmanueltouzery commented 4 years ago

hi, good effort, thank you for the PR! Well, first 'glabiboulga', i mean i needed something to append to differentiate, i could have put anything. I actually mistyped 'gloubi-boulga' which is from an old french kids cartoon :)

For the PR... I feel like what we have for the apidocs publishing currently is a workaround due to some limitations that typedoc had at the time. At the time I felt that typedoc development was not very active and I didn't expect the issues to be fixed relatively quickly (so much so that I didn't even report them).

So we do all this replacing specifically because:

# trick for the 'Option' & 'Either' constants which typedoc skips as it clashes
# with the 'Option' & 'Either' type synomym

So if we didn't rename, typedoc dropped the Option & Either constants, producing a bad apidoc (you can easily reproduce it by just commenting these workarounds). Then there is a second part to change 'files' to 'modules' but i mean we could also live with the modules terminology possibly. Then we have more tricks with typedoc, to get grouping for "Control", "Collection", "Core". There is a real chance that those bits will break due to the upgrade, but that part was already typescript, it's probably fixable. We could even possibly give up the feature, or try to achieve a similar effect by doing our own docs intro page linking to the typedoc api instead of hacking the typedoc HTML.

I don't even know how much longer we can hold on such an old version of typedoc, because typescript keeps adding features and that old typedoc doesn't know anything about the new stuff. It could stop being able to parse the source anytime. The typedoc version that prelude currently uses is 0.7.2... The latest is 0.17.7, and the project appears to have picked up steam.

So, rather than officializing the workarounds, I'd try to upgrade typedoc first, see how that looks like. Is the constant vs type synonym issue still present? If so, we could maybe make a little reproduction project, open them a bug, ask them how we should handle this.

What do you think? I'd rather try that first, and see where it takes us.

aleksei-berezkin commented 4 years ago

Hi thanks for your feedback. Well if the newer version of the tool produces the correct docs, it would be ideal just to migrate and not having hacks. However as I sad there's some inconvenience with tsconfig.base I'd like to fix probably in different PR. What do you think?

emmanueltouzery commented 4 years ago

yes i'm ok to change the tsconfig setup. i'm actually using emacs, this doesn't inconvenience me much, but i'm all for making it easy for others to use!