ionide / waypoint Goto Github PK

Describe the bug

When I install the Waypoint template and create a new instance of it using dotnet new Waypoint, the Docs generation target will fail.

To Reproduce

1. dotnet new -i Waypoint
2. mkdir WaypointTest
3. cd WaypointTest
4. dotnet new Waypoint
5. dotnet tool restore
6. dotnet fake build -t Docs

Expected behaviour
Docs generation succeeds.

Screenshots
If applicable, add screenshots to help explain your problem.

Environment (please complete the following information):

• OS: Ubutunu 20.04
• Ionide version: 4.11.1
• VSCode version: 1.45.1
• dotnet SDK version: 3.1.201
• mono / .Net Framework version: N/A

This was suggested by @dsyme yesterday on Twitter.

Core Design:

• As 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

It looks a bit noisy when every inline code segment has a "copy" button:

In my experience, inline code is most often used as a way of indicating parameter names or file names, and not, say, a CLI command or extended code. The example above, from the Waypoint wiki, demonstrates this.

I suggest either removing the copy button altogether, or hiding it until hover (or click on touch devices).

Is your feature request related to a problem? Please describe.
When writing documentation for libraries there are two (at least) problems:

1. keeping samples aligned with the current state of the library
2. providing very low friction ways for people to try out a library

Describe the solution you'd like
Fornax should support loader/generator that are able to consume .fsx files written using FSharp.Formatting .fsx literate programming pidgin. The reason this is useful now is that the new #r directive will allow those files to contain code the exercise a library with out any explicit project. Just references to Nuget.

The doc editing experience would be as follows:

• Write the sample code needed in an 'fsx file.
• Add documentation using the embedded markdown features
  NOTE: unfortunately there is no simple preview so that will depend on doing a build.

The docs generation pipeline would be as follows:

• Recognize .fsx file in the content area
• Apply the FSharp.Formatting transformations to HTML

The output on the site would be:

• Interleaved documentation and code describing how to use the library in a logical executable sequence top to bottom.
• Download link that let you download the source .fsx file

User interaction would be:

• Review the docs on line
• Download the .fsx and open the file in Ionide
• Execute parts of the file from top to bottom. If samples are written assuming the new 5.0 #r directive things should just work.

Why this is a Killer Feature for Fornax

1. Other static site generators can't easily integrate generation of code from .fsx files so will not be able to support the seamless read, then download, then try interaction model proposed here.
2. This approach can ensure the samples compile as the library evolves, no more outdated samples. Or samples with typo's

Hi there, this project looks really interesting, I will try it the next time i create a project from scratch. However, as you also mention in the docs, there are many projects around that initially used project scaffold which is kinda outdated.

As someone who manages some projects where this is the case, i have gradually changed features away from the initial project scaffold template and really dont want to start from a blank template again. I initially wanted to try fornax for documentation generation in a project, however fornax new creates a blog template. is there a way (other than copy pasting) to just use the awesome looking template from this library for a new fornax project in an existing codebase?

Step 2. says:

2. Run dotnet tool install to install all developer tools required to build the project

What does this mean? Running dotnet tool install does nothing. Should this read

2. Run dotnet tool install to install any additional developer tools required to build the project

Describe the bug
Trying to build a clean template generated with dotnet new waypoint and running dotnet fake build (after dotnet tool restore) i get the following error when running in a non-elevated shell. Everything works fine in an elevated shell.

There was a problem while setting up the environment:
-> symlink C:\Users\kevin\.nuget\packages\microsoft.netcore.targets\3.1.0 -> C:\Users\kevin\source\repos\WaypointTest2\packages\docs\Microsoft.NETCore.Targets failed with error : [1] with output :
    and error : You do not have sufficient privilege to perform this operation.
   StackTrace:
        at Microsoft.FSharp.Core.PrintfModule.PrintFormatToStringThenFail@1637.Invoke(String message) in E:\A\_work\130\s\src\fsharp\FSharp.Core\printf.fs:line 1637
        at SymlinkUtils.makeDirectoryLink(String target, String source)
        at [email protected](String _arg17)
        at Microsoft.FSharp.Control.AsyncPrimitives.CallThenInvokeNoHijackCheck[a,b](AsyncActivation`1 ctxt, FSharpFunc`2 userCode, b result1) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 417
        at <StartupCode$FSharp-Core>[email protected](AsyncActivation`1 ctxt) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 1066
        at <StartupCode$FSharp-Core>[email protected](AsyncActivation`1 ctxt) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 1066
        at [email protected](AsyncActivation`1 ctxt) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 589
        at [email protected](AsyncActivation`1 ctxt) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 589
        at [email protected](AsyncActivation`1 ctxt) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 589
        at [email protected](AsyncActivation`1 ctxt) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 589
        at [email protected](AsyncActivation`1 ctxt) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 589
        at Microsoft.FSharp.Control.Trampoline.Execute(FSharpFunc`2 firstAction) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 109
     --- End of stack trace from previous location where exception was thrown ---
        at Microsoft.FSharp.Control.AsyncResult`1.Commit() in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 349
        at Microsoft.FSharp.Control.AsyncPrimitives.RunSynchronouslyInCurrentThread[a](CancellationToken cancellationToken, FSharpAsync`1 computation) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 870
        at Microsoft.FSharp.Control.AsyncPrimitives.RunSynchronously[T](CancellationToken cancellationToken, FSharpAsync`1 computation, FSharpOption`1 timeout) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 890
        at Microsoft.FSharp.Control.FSharpAsync.RunSynchronously[T](FSharpAsync`1 computation, FSharpOption`1 timeout, FSharpOption`1 cancellationToken) in E:\A\_work\130\s\src\fsharp\FSharp.Core\async.fs:line 1151
        at [email protected](Unit unitVar0)
        at Paket.Utils.RunInLockedAccessMode[a](String lockedFolder, FSharpFunc`2 action)
        at Paket.RestoreProcess.Restore(String dependenciesFileName, RestoreProjectOptions projectFile, Boolean force, FSharpOption`1 group, Boolean ignoreChecks, Boolean failOnChecks, FSharpOption`1 targetFrameworks, FSharpOption`1 outputPath, Boolean skipRestoreTargetsExtraction)
        at Fake.Runtime.FakeRuntime.paketCachingProvider(FakeConfig config, String cacheDir, Dependencies paketApi, Lazy`1 paketDependenciesFile, FSharpOption`1 group) in D:\a\1\s\src\app\Fake.Runtime\FakeRuntime.fs:line 345
        at Fake.Runtime.FakeRuntime.runScript(PrepareInfo preparedScript) in D:\a\1\s\src\app\Fake.Runtime\FakeRuntime.fs:line 596
        at Program.runOrBuild(RunArguments args) in D:\a\1\s\src\app\Fake.netcore\Program.fs:line 156

Ionide fails to load the projects as well when run in non-elevated VSCode (i guess this is because it tries to run dotnet restore?). It works here aswell when running vscode elevated.

To Reproduce
Steps to reproduce the behaviour:

1. install latest waypoint template (dotnet new -i waypoint)
2. create clean new template (dotnet new waypoint)
3. open in non-elevated vscode
4. dotnet tool restore and then dotnet fake build in non elevated shell

Expected behaviour
project builds and can be loaded in vscode

Environment (please complete the following information):

• OS: Windows 10 Pro 1909 18363.836
• Ionide version: 4.11.0
• VSCode version: 1.45.1 (user setup)
• dotnet SDK version: 3.1.201

Describe the bug
I can't run dotnet fornax build or dotnet fornax watch successfully in the docs folder of the Content template on MacOS.

To Reproduce

1. Clone repo and cd to Content
2. run dotnet tool restore
3. run dotnet fake build to ensure library is built
4. cd to docs
5. run dotnet fornax build
6. The build errors with something like

➜  docs git:(doubleslash) ✗ dotnet fornax watch
LOADER ERROR: Load Errors: [|/Users/chethusk/oss/Waypoint/Content/docs/loaders/literalloader.fsx (116,43)-(116,55) typecheck error The value, namespace, type or module 'PostCategory' is not defined. Maybe you want one of the following:
   Poster;
  /Users/chethusk/oss/Waypoint/Content/docs/loaders/literalloader.fsx (119,7)-(119,11) typecheck error The record label 'file' is not defined.;
  /Users/chethusk/oss/Waypoint/Content/docs/loaders/literalloader.fsx (139,26)-(139,44) typecheck error The record label 'disableLiveRefresh' is not defined.|]
Open Errors: [|input.fsx (1,6)-(1,19) typecheck error The namespace or module 'Literalloader' is not defined.|]
Get layout Errors: [|input.fsx (1,16)-(1,22) typecheck error The value or constructor 'loader' is not defined. Maybe you want one of the following:
   Loading
   Order|]
[14:01:33] multiple files generated in 113ms
[14:01:34] '/Users/chethusk/oss/Waypoint/Content/docs/_public/index.json' generated in 340ms
[14:01:34] '/Users/chethusk/oss/Waypoint/Content/docs/_public/explanations/some-post.html' generated in 422ms
[14:01:35] '/Users/chethusk/oss/Waypoint/Content/docs/_public/explanations/overview.html' generated in 684ms
[14:01:35] '/Users/chethusk/oss/Waypoint/Content/docs/_public/tutorials/some-post.html' generated in 504ms
[14:01:36] '/Users/chethusk/oss/Waypoint/Content/docs/_public/tutorials/how-to-start.html' generated in 419ms
[14:01:36] '/Users/chethusk/oss/Waypoint/Content/docs/_public/how-tos/somePostWithCode.html' generated in 421ms
[14:01:37] '/Users/chethusk/oss/Waypoint/Content/docs/_public/how-tos/diagrams.html' generated in 390ms
An unexpected error happend: System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
 ---> System.Collections.Generic.KeyNotFoundException: An index satisfying the predicate was not found in the collection.
   at Microsoft.FSharp.Collections.SeqModule.Find[T](FSharpFunc`2 predicate, IEnumerable`1 source) in F:\workspace\_work\1\s\src\fsharp\FSharp.Core\seq.fs:line 677
   at FSI_0046.Page.generate'(SiteContents ctx, String page)
   at lambda_method(Closure , Unit , SiteContents , String , String )
   --- End of inner exception stack trace ---
   at System.RuntimeMethodHandle.InvokeMethod(Object target, Object[] arguments, Signature sig, Boolean constructor, Boolean wrapExceptions)
   at System.Reflection.RuntimeMethodInfo.Invoke(Object obj, BindingFlags invokeAttr, Binder binder, Object[] parameters, CultureInfo culture)
   at Generator.EvaluatorHelpers.helper@54(Object next, FSharpList`1 args) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Generator.fs:line 64
   at Generator.EvaluatorHelpers.invokeFunction(Object f, IEnumerable`1 args) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Generator.fs:line 68
   at [email protected](FsiValue ft) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Generator.fs:line 178
   at Microsoft.FSharp.Core.ResultModule.Bind[T,TResult,TError](FSharpFunc`2 binder, FSharpResult`2 result) in F:\workspace\_work\1\s\src\fsharp\FSharp.Core\result.fs:line 15
   at Generator.GeneratorEvaluator.evaluate(FsiEvaluationSession fsi, SiteContents siteContent, String generatorPath, String projectRoot, String page) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Generator.fs:line 175
   at Generator.generate(FsiEvaluationSession fsi, Config cfg, SiteContents siteContent, String projectRoot, String page) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Generator.fs:line 321
   at Generator.action@1(String projectRoot, FsiEvaluationSession fsi, Config config, SiteContents sc, String filePath) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Generator.fs:line 479
   at Generator.generateFolder(String projectRoot, Boolean isWatch) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Generator.fs:line 478
   at Fornax.guardedGenerate@168(String cwd, Unit unitVar0) in D:\Programowanie\Projekty\Ionide\Fornax\src\Fornax\Fornax.fs:line 170

I think the problem here is that the literal loader can't typecheck correctly, which causes a fault in the page generator later on.

Expected behaviour
The api, content, and search docs are all build.

Environment (please complete the following information):

• OS: macos catalina
• dotnet SDK version: 3.1.300

Add a link to download md or fsx files that are used for a content generation - more in-depth discussion in #22

Since Waypoint is opinionated regarding coding style, there should be an .editorconfig and a fantomas-config.json in the project root to make IDEs that support these files (e.g. VSCode, and VS at least supports .editorconfig) automatically use the correct settings.

For more easily getting contributions for fixing typos in the docs, it would be great to have a button/link on each page pointing to the source for that page. (For API reference, this might point to the relevant code file.)

Similarly to the way ProjectScaffold did it with an init script, Waypoint could fill the TODOs left in e.g. build.fsx via a script that gets executed after template initiation. The functionality I refer to would be added to the postActions section of the template.json (https://github.com/dotnet/templating/wiki/Post-Action-Registry)

Is this a feature that would fit/ is wanted? If so, i could have a go at implementing it.

Search engine optimisations to improve F#-tooling-awareness.

Besides the current <title> The templates should generate the following meta tags content to the page <header>, at least descriptions, keywords, etc:

<meta property="og:site_name" content="Product name">
<meta name="description" content="Small description of the project." />
<meta name="keywords" content="fsharp" />
<meta property="og:image" content="http://non-ssl-path-logo.png">
<meta property="og:image:secure_url" content="https://.../logo.png">
<link rel="apple-touch-icon-precomposed" sizes="144x144" href="/logo.png" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@fsharporg" />
<meta name="robots" content="index,follow" />
<meta name="rating" content="general" />

I think url-routing is quite ok as it is, but the double-slash could be removed, e.g.:
https://moiraesoftware.github.io/myriad//tutorials/debugging.html