FSharp.Formatting icon indicating copy to clipboard operation
FSharp.Formatting copied to clipboard

Resolve links in docs for F# libraries to types defined in FSharp.Core

Open dsyme opened this issue 5 years ago • 6 comments

We currently give links for intra-collection types and .NET types, but not for FSharp.Core

Now FSharp.Core is getting more stable, linkable docs we can start to generate links for types coming from there,

For example, note how "float" doesn't have links here. We could link to https://fsharp.github.io/fsharp-core-docs/reference/fsharp-core-float.html. On the assumption that URI is sufficiently stable (cc @baronfel @cartermp :-) )

image

dsyme avatar Aug 06 '20 03:08 dsyme

@cartermp this was the main reason I had hoped to use a root URL of either

docs.fsharp.org/FSharp.Core 

or

fsharp.github.io/docs/FSharp.Core

Both potentially feel long term canonical for inward links, even if potentially eventually redirecting to the dotnet docs once FSharp.Core docs go there

The current URL we are using for FSharp.Core docs is not too bad, but I'd prefer something very long-term canonical (to avoid a situation where we start auto generating urls to places where we may make later changes)

dsyme avatar Aug 08 '20 00:08 dsyme

@cartermp How do you feel about this? I'd really love to be able to generate links into FSHarp.Core docs, but we need stable long term URLs for that.

It it possible to at least please change

fsharp.github.io/fsharp-core-docs/FSharp.Core 

to

fsharp.github.io/docs/FSharp.Core 

?? But ideally we'd use the ultra-canonical

docs.fsharp.org/FSharp.Core

dsyme avatar Aug 14 '20 12:08 dsyme

The last one would be great if possible. I'm fine with that. Just want to mainly ensure it's clear that it's for FSharp.Core.

Note that I made a lot of changes in these PRs and they would need adjusting again: https://github.com/dotnet/docs/pulls/cartermp

cartermp avatar Aug 14 '20 15:08 cartermp

@cartermp What would be the process to get docs.fsharp.org/FSharp.Core?

I'm still tempted by

fsharp.github.io/docs/FSharp.Core 

since it is still pretty canonical by industry standards

dsyme avatar Apr 15 '21 15:04 dsyme

Doing fsharp.github.io/docs/FSharp.Core would require updating https://github.com/fsharp/fsharp.github.io, I believe, since the 'bare' <user>.github.io domains are controlled by the content in a <user>.github.io repository. The question would be how to transparently do the redirects there...or would that repo just start handling generation of Fsharp.Core API docs? (not a bad idea)

baronfel avatar Apr 15 '21 15:04 baronfel

@baronfel I think we'd just have to rename fsharp-core-docs repo to docs and generate a"FSharp.Core" prefix

Since the current name maps to fsharp.github.io/fsharp-core-docs

dsyme avatar Apr 15 '21 17:04 dsyme