Upgrade FSharp.Formatting / fsdocs #369

adz · 2020-10-10T04:31:06Z

This changes the doc structure to suit fsdocs, so we can use the command line version, and get improved layout as per https://fsprojects.github.io/FSharp.Formatting/upgrade.html

With this change, you can build a local web-served version of docs (once built, it opens the browser to the local docs, and I get local paths, and instant rebuild as I save - the docs, but not the api ref docs unfortunately):

dotnet fsdocs watch --projects src/FSharpPlus/FSharpPlus.fsproj --input docsrc/

Using this variant builds to the docs folder:

dotnet fsdocs build --projects src/FSharpPlus/FSharpPlus.fsproj --input docsrc/ --output docs/

@wallymathieu at first I thought we didn't need the code in docsrc/tools any more since the docs can be generated via this command, but then I noticed the plantuml replacement, and there is the github-pages releasedocs target. I can follow the code that does the work, but I am not sure what to do to integrate it.

I'm thinking we:

Delete docsrc/tools
Take a clean fake build script like https://github.com/dsyme/FSharp.Control.AsyncSeq/blob/6982e50dcc81e59f49221bd1059582b84918c001/build.fsx and use it with adjustments. WDYT?

I'm not sure you agree, or have a better idea, as I"m also unsure of how the nuget release is done, etc.

adz · 2020-10-10T04:33:29Z

docsrc/_template.html

+                <li class="nav-item" id="fsdocs-repository-link"><a class="nav-link" href="{{fsdocs-repository-link}}">Source Repository</a></li>
+
+                <!-- Do not use 'fsdocs-list-of-documents' which currently cannot be ordered, and dumps all files in docsrc/ -->
+                <li class="nav-header" style="padding-top: 10px">Documentation</li>


The default template has {{fsdocs-list-of-documents}} but this doesn't work well, since it just lists all the files in docsrc/* and dumps them into the menu (so all the type-* files, and abstraction-*). A lot of them don't produce titles, and you can't order them.

I decided to put these manually there and the result is pretty good:

This looks nice 👍

adz · 2020-10-10T04:36:11Z

src/FSharpPlus/Operators.fs

@@ -9,102 +9,176 @@ module Operators =

    // Common combinators

-    /// Creates a new function with first two arguments flipped.
+    /// <summary>Creates a new function with first two arguments flipped.</summary>
+    /// <category>common</category>
    let inline flip f (x: 'T) (y: 'V) : 'Result = f y x


These categories are only partially done, but give a nice table of contents. It's no big issue since functions without a category get put into "Other module members":

wallymathieu · 2020-10-10T06:22:59Z

The docs are built independently of nuget releases.

wallymathieu · 2020-10-10T06:38:42Z

I'm trying to run the tool but I get:

cracking projects...
  skipping project 'FSharpPlus.fsproj' because it doesn't have a target path

Perhaps related to this issue:
fsprojects/FSharp.Formatting#574

wallymathieu · 2020-10-10T06:51:17Z

The main reason from the doc generation is right now:

Documentation written in fsx files
Visual overview of the abstractions as seen in the plantuml file
API docs

wallymathieu · 2020-10-10T08:29:33Z

I might be able to help out to see about getting some of the things to build. Perhaps we could see about how we should render the plantuml, it might be related to a similar question around using charts in fsprojects/FSharp.Formatting#611

adz · 2020-10-10T11:58:33Z

Oh sorry @wallymathieu

Add this to the command, or set it in env somehow:

 TargetPath=src/FSharpPlus/bin/Debug/netstandard2.0/FSharpPlus.dll

I had to do this, as was getting the same error, but after a full build of solution, I didn't seem to need it anymore.

In regards to your comment:

The main reason from the doc generation is right now:
Documentation written in fsx files
Visual overview of the abstractions as seen in the plantuml file
API docs

This fsdocs command does the 1st and 3rd, but not the 2nd.

We could keep the doc project, and have it call out to fsdocs, then follow up with plantuml, but I was thinking it might be better to use a top level build.fsx fake script.

wallymathieu · 2020-10-10T13:14:38Z

We used to have a FAKE script to generate the docs. I think there was some issues that made it easier to avoid FAKE and paket.

adz · 2020-10-10T13:24:15Z

Yes it was a bit messy pre dotnet core. As well, the build file was more complicated than needed. Now with v3 local tools it seems OK.

Also the doc project we have now seems to pull in some fake code anyway.

If docs are independent I'll have a try when I can in the next few days.

wallymathieu · 2020-10-10T14:25:29Z

I'm unsure if that was the issue. Let's see if we can get this to work without taking a dependency on paket for everything (since that impacts the full build). The recent iterations of f# formatting have some nice improvements that we can benefit from 🙂

wallymathieu · 2020-10-10T16:59:27Z

The doc project we have now have a local dumbed down version of FAKE defined in the tools folder. I've pushed changes to appveyor and travis configuration in order for them to build the docs for this branch.

So what's left right now in this PR?

How to deploy to docs (I'm guessing that there are some examples of this in other projects)
Visual overview of the abstractions as seen in the plantuml file (I'm guessing that this is the most painful thing)
Make sure that the build is green

gusty · 2020-10-10T17:17:01Z

Can we put all the source files from this PRs, those that you enhanced the XML comments, in a separate PR?

Because I think that's independent of which doc build we use.

I will also reduce the amount of code to review here.

* Copy current template from fsdocs to docsr/_template.html * Move docsrc/content and docsrc/files to root of docsrc * Update paths to suit that move * Remove unused docsrc/tools/templates

wallymathieu · 2020-10-10T21:05:28Z

I'm thinking of upgrading the doc generation in this PR #372 so that we can use the way nicer template you have made and the documentation improvements without losing the ability to modify some of the expressions.

adz · 2020-10-10T21:19:32Z

@gusty I removed the xml doc changes, but note that most of the changes are just "../../doc" to "../doc" since fsdocs expects the docs to mirror the final path (i.e. not under content or files).

@wallymathieu happy for you to do that -- but note that if you upgrade and use fsdocs there are the path changes I mentioned. We might have to combine the changes in this PR at the same time, or the docs will build with the folder in the path (eg: "https://fsprojects.github.io/FSharpPlus/content/operators-common.html" - note the 'content').

wallymathieu · 2020-10-10T21:24:11Z

Yes, I'm trying to dive a bit into F# Formatting command line tool in order to get an idea how it works.

gusty · 2020-10-11T12:40:52Z

@gusty I removed the xml doc changes, but note that most of the changes are just "../../doc" to "../doc" since fsdocs expects the docs to mirror the final path (i.e. not under content or files).

No worries, I'm fine with that.

wallymathieu · 2020-10-11T18:06:37Z

I have a finished PR with upgrade of the infrastructure and github pages deployment code so that we can turn this PR into a PR for the _template.html file and such.

wallymathieu

Taking the weed wacker out can be useful, but I think we lost more that we bargained for

wallymathieu · 2020-10-13T05:25:37Z

docsrc/_template.html

+                <li class="nav-item" id="fsdocs-repository-link"><a class="nav-link" href="{{fsdocs-repository-link}}">Source Repository</a></li>
+
+                <!-- Do not use 'fsdocs-list-of-documents' which currently cannot be ordered, and dumps all files in docsrc/ -->
+                <li class="nav-header" style="padding-top: 10px">Documentation</li>


This looks nice 👍

wallymathieu · 2020-10-13T05:26:19Z

docsrc/abstraction-alternative.fsx

@@ -1,7 +1,7 @@
 (*** hide ***)
 // This block of code is omitted in the generated HTML documentation. Use 
 // it to define helpers that you do not want to show in the documentation.
-#I "../../bin"
+#I "../bin"


You can specify input to the tool in order to have another folder than the default.

wallymathieu · 2020-10-13T05:27:39Z

docsrc/generic-doc.fsx

@@ -136,7 +136,7 @@ For a type defined in an external library it will work when it contains a static

 Here's an example of the generic function ``fromBigInt`` targeting a type defined in the MathNet library
 *)
-#r "../../packages/docs/MathNet.Numerics/lib/net40/MathNet.Numerics.dll"
-#r "../../packages/docs/MathNet.Numerics.FSharp/lib/net45/MathNet.Numerics.FSharp.dll"
+#r "../packages/docs/MathNet.Numerics/lib/net40/MathNet.Numerics.dll"


these are added through download nuget scripts, so by deleting the tools folder you will need to download these another way.

wallymathieu · 2020-10-13T05:29:09Z

docsrc/tools/generate.fs

@@ -1,142 +0,0 @@
-module Generate


from what we can see in the other PR, this file is no longer needed

wallymathieu · 2020-10-13T05:30:24Z

docsrc/tools/Program.fs

@@ -1,191 +0,0 @@
-// Learn more about F# at http://fsharp.org


the code here is needed (as seen in the other PR), but could be turned into a FAKE script

wallymathieu · 2020-10-13T05:31:56Z

docsrc/tools/doclib.fs

@@ -1,1247 +0,0 @@
-module DocLib


Note this is a dumbed down version of FAKE v4

wallymathieu · 2020-10-13T05:36:42Z

docsrc/tools/download_nugets.ps1

-    & $nuget install FSharp.Core "-ExcludeVersion" "-version" 4.6.2 "-source" https://www.nuget.org/api/v2 "-OutputDirectory" packages/docs/
-    & $nuget install System.Runtime "-ExcludeVersion" "-version" 4.3.1  "-source" https://www.nuget.org/api/v2 "-OutputDirectory" packages/docs/
-    & $nuget install MathNet.Numerics.FSharp "-ExcludeVersion" "-version" 4.8.1  -source https://www.nuget.org/api/v2 "-OutputDirectory" packages/docs/
-    & $nuget install FSharp.Literate "-ExcludeVersion" "-version" 4.0.0-alpha03  -source https://www.nuget.org/api/v2 "-OutputDirectory" packages/docs/


I think most of these downloads are not needed anymore, the only ones that are relevant are the ones that are referenced from the scripts.

wallymathieu · 2020-10-13T05:37:07Z

docsrc/tools/templates/abstractions.plantuml

@@ -1,134 +0,0 @@
-@startuml


we still want to keep this image around

wallymathieu · 2020-10-13T11:15:18Z

I've done a PR on F# formatting in order to avoid the workaround: fsprojects/FSharp.Formatting#613

adz commented Oct 10, 2020

View reviewed changes

adz requested a review from wallymathieu October 10, 2020 04:37

Use fsdoc cli tool

f26a359

* Copy current template from fsdocs to docsr/_template.html * Move docsrc/content and docsrc/files to root of docsrc * Update paths to suit that move * Remove unused docsrc/tools/templates

adz force-pushed the adz-fsdocs branch from a288911 to f26a359 Compare October 10, 2020 20:51

wallymathieu requested changes Oct 13, 2020

View reviewed changes

wallymathieu mentioned this pull request Oct 13, 2020

Update to latest F# Formatting #372

Merged

3 tasks

adz closed this Oct 26, 2020

adz deleted the adz-fsdocs branch October 26, 2020 20:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Upgrade FSharp.Formatting / fsdocs #369

Upgrade FSharp.Formatting / fsdocs #369

adz commented Oct 10, 2020

adz Oct 10, 2020

wallymathieu Oct 13, 2020

adz Oct 10, 2020

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

adz commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

adz commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020 •

edited

Loading

gusty commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

adz commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

gusty commented Oct 11, 2020

wallymathieu commented Oct 11, 2020 •

edited

Loading

wallymathieu left a comment

wallymathieu Oct 13, 2020

wallymathieu Oct 13, 2020

wallymathieu Oct 13, 2020

wallymathieu Oct 13, 2020

wallymathieu Oct 13, 2020

wallymathieu Oct 13, 2020

wallymathieu Oct 13, 2020

wallymathieu Oct 13, 2020

wallymathieu commented Oct 13, 2020

		@@ -1,191 +0,0 @@
		// Learn more about F# at http://fsharp.org

Upgrade FSharp.Formatting / fsdocs #369

Upgrade FSharp.Formatting / fsdocs #369

Conversation

adz commented Oct 10, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

adz commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

adz commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

wallymathieu commented Oct 10, 2020 • edited Loading

gusty commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

adz commented Oct 10, 2020

wallymathieu commented Oct 10, 2020

gusty commented Oct 11, 2020

wallymathieu commented Oct 11, 2020 • edited Loading

wallymathieu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wallymathieu commented Oct 13, 2020

wallymathieu commented Oct 10, 2020 •

edited

Loading

wallymathieu commented Oct 11, 2020 •

edited

Loading