Guidance on literate programming

[TheAngryByrd]

I'm looking for some guidance on how to deal with a specific problem when doing Literate Prgramming. This involves trying to update the doc's examples with new code that isn't available yet on nuget.

For example lets say I have this snippet:

#r "nuget: FsToolkit.Errorhandling"
open FsToolkit.ErrorHandling

let test : Result<int,string> = result { return 4 }

test
|> Result.map (fun x -> x * 2)
|> printf "A result is: %A" 
(*** include-output ***)

but then I added a new Result.someCoolThing function.

#r "nuget: FsToolkit.Errorhandling"
open FsToolkit.ErrorHandling

let test : Result<int,string> = result { return 4 }

test
|> Result.someCoolThing (fun x -> x * 2)
|> printf "A result is: %A" 
(*** include-output ***)

However, since I haven't published the nuget package yet, this wouldn't work. Is there any good tips/guidance on dealing with this problem?

---

I've looked into Referencing projects with #r: fsproj but I couldn't get this to work. Also with this workaround, I wouldn't necessarily want to show the referencing of the project or dlls, but only the nuget package so people would be easily able to copy snippets from the published docs.

[baronfel]

One thing to do might be to build the docs after you package the local copy. When you build the docs, you can use a nuget.config file that specifies the location of the built package as an additional package source. That would keep you from having to specify the local source in the documentation files themselves, which means that after you publish the package to NuGet.org users could just copy and paste directly.

[TheAngryByrd]

Yeah this seems to work somewhat. The problem here is once you reference a nuget package, you'd have to go clear out your local nuget cache if you have to regenerate the package for any reason. Is there some type of way to get FSI to force reinstall those local packages? (Or maybe not cache to begin with Looks like people have been asking for this for a while.)

Do you foresee any other issues with having some output package directory always in the NuGet.config file?

[baronfel]

If that directory doesn't exist then dotnet restore/FSI will report errors. To get around that I commit a dummy file to the folder, but I also put the folder under gitignore to prevent packages being checked in.

Another thing to do would be to set a different global packages dir to prevent corrupting your global cache. I forget the nuget.config setting for that, but I think it's the NUGET_PACKAGES env var.

[nhirschey]

You can use a hidden (*** condition:prepare ***) section to reference the dlls explicitly.

https://github.com/fsprojects/FSharp.Data/blob/main/docs/library/CsvProvider.fsx

you can then fake a reference to the nuget within a markdown comment block. See also

https://github.com/DiffSharp/DiffSharp/blob/29af24ad69a96aace8a49420996861b2a3ca0fa9/docs/install.fsx#L49

If you use {{fsdocs-package-version}} you can automatically update to latest your nuget version on publication, see the diffsharp docs use of it. I think fsharp data uses that trick too.

Here’s a use of package version
https://github.com/fsprojects/FSharp.Data.Toolbox/blob/4cd853c39ffa2131976f9681b4837dd88731cb58/docs/TwitterProvider.fsx#L41

[TheAngryByrd]

Another thing to do would be to set a different global packages dir to prevent corrupting your global cache. I forget the nuget.config setting for that, but I think it's the NUGET_PACKAGES env var.

Yeah this is possible but it's a very weird experience making this work. If you don't set NUGET_PACKAGES before you open your editor, it won't pick up these changes.

If you only set it for the dotnet fsdocs command itself, it doesn't seem to pull from the new cache.

Content:
  generating model for C:\Users\jimmy\Repositories\public\TheAngryByrd\fsdocstster\docsSrc\Tutorials\Tutorial-3.fsx --> .\Tutorials\Tutorial-3.html
   C:\Users\jimmy\Repositories\public\TheAngryByrd\fsdocstster\docsSrc\Tutorials\Tutorial-3.fsx: error(20,17)-(20,20) The value, constructor, namespace or type 'Foo' is not defined.
   C:\Users\jimmy\Repositories\public\TheAngryByrd\fsdocstster\docsSrc\Tutorials\Tutorial-3.fsx: error(0,0)-(0,0) The module/namespace 'Project1.Say' from compilation unit 'Project1' did not contain the namespace, module or type 'Foo'

---

You can use a hidden (*** condition:prepare ***) section to reference the dlls explicitly.

https://github.com/fsprojects/FSharp.Data/blob/main/docs/library/CsvProvider.fsx

you can then fake a reference to the nuget within a markdown comment block. See also

This is good to know! Only problem I have here is it becomes difficult to reference a project if it has dependencies. Yeah, you can generate it load references in VSCode but in my experience, the load order isn't correct always.

f you use {{fsdocs-package-version}} you can automatically update to latest your nuget version on publication, see the diffsharp docs use of it. I think fsharp data uses that trick too.

This issue is more about before publication of the nuget package but still valuable to know. Thanks!

[TheAngryByrd]

The package caching wouldn't be so bad if NuGet locals command should allow deleting specific packages from NuGet global packages folder was available also. :(

[nhirschey]

This issue is more about before publication of the nuget package.

Just fyi for future reference, fsdocs takes {{fsdocs-package-version}} from your project or directory build props, not nuget.org. There’s no nuget dependency. It’ll work pre-publication.

[nojaf]

Not sure if this helps but in Fantomas, we switched to local assemblies instead of #r "nuget::
https://github.com/fsprojects/fantomas/blob/v6.0/docs/docs/end-users/Configuration.fsx#L18-L19

[kMutagene]

In Plotly.NET, we use local assembly references as well. If your project has external dependencies, they can be loaded via #r nuget:

https://github.com/plotly/Plotly.NET/blob/1e5fec1496e5b78dc4bb7cad7648a95cefdb975a/docs/02_0_line-scatter-plots.fsx#L12-L16

[dsyme]

/repo-assist chime in here with an opinion please old man

[github-actions]

🤖 This is an automated response from Repo Assist.

Happy to chime in! Having read the thread, here's my take:

The (*** condition:prepare ***) approach is the right long-term pattern. It's what FSharp.Data, Fantomas, Plotly.NET, and DiffSharp all converged on, and for good reason:

• No NuGet caching headaches — you're loading the DLL you just built
• Docs can be built at any point during development, not just after a publish
• End-users see the clean #r "nuget:" snippet in published docs because the prepare block is hidden
• External dependencies can still use #r "nuget:" normally (they're already on NuGet)

The rough pattern is:

(*** condition:prepare ***)
#r "../path/to/output/YourLibrary.dll"
#r "nuget: SomeDependency"

(*** hide ***)
// This is what readers see in the rendered docs

To use this library, add:
    #r "nuget: YourLibrary, {{fsdocs-package-version}}"

The local nuget feed approach (nuget.config pointing at a local packages dir) is workable too, but it has the cache invalidation problem you hit, and it requires a pack step before docs. I'd treat it as a fallback.

One thing worth noting as a potential fsdocs improvement: it would be nice if fsdocs supported a --packages-dir flag or a nuget.config substitution that let you override package sources at doc-generation time without touching the scripts themselves. That way you could write #r "nuget: YourLibrary" in your scripts and have it redirect to a local feed only during doc builds. If this is a pattern people want, it might be worth an enhancement issue — the (*** condition:prepare ***) workaround is effective but a bit awkward to set up for the first time.

For now I'd recommend following the FSharp.Data/Fantomas pattern — it's battle-tested.

Generated by Repo Assist for issue #804 · ◷

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@10f087607af87e4e89439161f1e5d4724235f396