Support .inv generation to enable integration with sphinx generated sites

[lextm]

I have several sites generated by sphinx, but want to integrate them with a site generated by docfx.

Since reStructuredText won't be supported (per #104), is it possible for a docfx project to emit .inv file so that integration with sphinx generated sites can be achieved?

A sphinx generated site can use intersphinx to add references to another sphinx generated site,

http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

The .inv file can be parsed by a gist like this,

https://gist.github.com/epc/4118456

I am not sure how it should be generated though, but docutils is open source so there should be a way to dig that out.

Once docfx can generate .inv for a site, then it can be used by sphinx generated sites and achieve tight integration with each other.

ASP.NET 5 and .NET Core 5 have their contents running on sphinx and reStructuredText, so probably this feature can help them too.

[chenkennt]

Hi lextm, we understand the need for cross reference between docfx projects and with other documentation sites. To support this, we plan to generate a map file that contains all files' information like url and title (actually very similar to the concept of inventory file). It should contain enough information so you'll be able write some custom code to convert it to an inv file that can be consumed be Sphinx.

[lextm]

@chenkennt, thanks. Look forward to that.

[johnneycao]

#240

[chenkennt]

DocFX now generates a xrefmap.yml which includes all topics that have uid, which can be used by other docfx projects for external reference. You can also write your own code to convert it to a file that can be consumed by Sphinx. Take a look at this file as an example of how xrefmap file looks like.