ionide / ionide/Waypoint

Moving (parts of) documentation generation scripts to the compiled dll

Open
#25 11 comments 1 reaction 0 assignees View on GitHub
documentation question
Dominant language
F#
Stars
73
Forks
13
PR merge metrics
No merged PRs in 30d

Description

This was suggested by @dsyme yesterday on Twitter.

Core Design:
* As [Fornax](https://github.com/ionide/Fornax) is essentially just an opinionated script runner there is no way (by-design) to remove `.fsx` scripts completely.
* We could potentially move parts of the scripts (for example API reference generation etc) to compiled DLLs - and our generators/loaders `.fsx` would just contain a reference to this DLL and single one-line function call

Pros:
* Easy to update to a new version (just run `paket update` on the Docs group)
* Hides internal API changes (for example users doesn't need to know that F#.Formatting API has changed)
* Provides a single opinionated way of how documentation should be build - good for consistency across our OSS ecosystem

Cons:
* Provides a single opinionated way of how documentation should be build - different projects may have different needs
* Lack of customizability - a huge advantage of having those scripts in the repo is the fact you can just easily change them to make them fit project needs better
* Distribution story when not using Paket - since plain NuGet nowadays installs packages globally there won't be an easy way to reference this library from our generators/loaders scripts (Maybe solved by `#r nuget` - but keep in mind it's still a preview feature)

CC: @baronfel

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.