Docfx: Feature Request: cross reference to Sandcastle website

[SamuelEnglard]

It's great being able to cross reference other projects that use DocFx but there's no way currently to do the same for projects that use Sandcastle.

I tried building a simple XrefService that would take the UID and return the Sandcastle site's page but a UID is not enough to do that it seemed.

[superyyrrzz]

Using an xref map is enough. Of course, you need to generate this xrefmap for your Sandcastle site.

[SamuelEnglard]

If it was my site that be one thing but it's not (JSON.NET in this case). I figured a service would make more sense since it could be one service for any site.

[superyyrrzz]

Got your ideas. There is an existing XrefSevice for docs.microsoft.com site. When a page is published, it will feed data into this service.

Back to your case. As the site is from third part, it cannot push date into your XrefService. Instead, your XrefService should pull data from the Sandcastle site.

Given you have already pull the data, it does not matter to use XrefService or XrefMap as the interface to DocFX. Personally, I think it is easier to prepare a file instead of setting up a service.

[SamuelEnglard]

That is a good point about XrefMap being easier. I'll have to experiment with that.

[superyyrrzz]

Looks like this will be a tool applied for all Sandcastle generated sites. Welcome to contribute to docfx codebase 😄

[SamuelEnglard]

Is a UID just the value of a full type reference without the type ident? So M:Newtonsoft.Json.DefaultJsonNameTable.#ctor becomes Newtonsoft.Json.DefaultJsonNameTable.#ctor?

[superyyrrzz]

Yes: https://dotnet.github.io/docfx/spec/metadata_dotnet_spec.html#21-unique-identifiers

[SamuelEnglard]

That's what I though but wanted to double check 😄

[SamuelEnglard]

Quick update: I have a working prototype. Working on polishing it up and I'll make a pull request

[superyyrrzz]

Great! It can go to tools: https://github.com/dotnet/docfx/tree/dev/tools

[superyyrrzz]

Released: https://www.nuget.org/packages/SandcastleRefMapper/