Publish a docfx-compatible xref file or service

[jskeet]

I'm expecting Docfx to be gradually adopted by more and more projects, especially as it's the engine powering docs.microsoft.com. We're using it for the Noda Time docs, for example.

It would be lovely to be able to generate links from our documentation to the Json.NET documentation (e.g. for parameters, return types). I believe that should be feasible without Json.NET itself adopting docfx, if we could create an xref map file (sample from NodaTime). I suspect that would be most simply generating as part of the existing API documentation build system - hopefully it creates a master table of contents file somewhere that could then be transformed into a docfx one.

I'm happy to look into this with a bit more information about any intermediate files created by the docs build.

[JamesNK]

I don't have any plans to move off Sandcastle. Does it support generating the file?

[jskeet]

Definitely not suggesting moving off Sandcastle. (All the broken links around the world would be a nightmare to start with...)

Not sure what the "it" is here - I doubt that Sandcastle supports generating the xref file directly, but I was hoping that one of the intermediate build outputs of Sandcastle (some kind of machine-readable TOC) would be suitable for us to use as an input to a custom (hopefully very small) generation process.

I don't know much about the Json.NET docs build process - if you're in a position to have a quick look for anything that looks like it might be suitable and either make it publicly available or email it to me, I'd be happy to try to prototype something.

[jskeet]

Looking a bit closer, I suspect I can generate an xref file straight from the assembly, at least if I only need to worry about the types. Other members are slightly trickier (the generated URLs for overloads are just numbered, rather than being independently predictable) but for the majority of use cases (parameter types, return types) this should be absolutely fine. I'll prototype and let you know how I get on. (If it works just well enough for me but you'd prefer not to host it alongside the documentation, it's fine for me to just have it locally.)

[jskeet]

I've built a prototype which is good enough for my needs, but may well not handle everything (and only even attempts to handle types). If it's useful to you, feel free to use it - if not, my needs are met anyway :) https://github.com/nodatime/nodatime.org/blob/07a6fbf9b199c99b27c47ca77182f778e5c03ce0/build/SandcastleXrefGenerator/Program.cs

[shmuelie]

There is now an tool in DocFx for this https://github.com/dotnet/docfx/blob/dev/tools/SandcastleRefMapper/Program.cs (written for importing JSON.Net in fact)

[jskeet]

@SamuelEnglard: Nice! Thanks for letting me know. Will schedule killing my own one, assuming I can get the docfx to work.

[Lulalaby]

Would really love to see that as well