intersphinx mapping

[madeline-scyphers]

I am working on a project that uses sphinx to build the docs. We use intersphinx to cross link to other projects and we would like to link to Ax for type hints and other resources. Because in Ax's docs scripts, after you build your docs with sphinx, you copy the html files for docusaurus and then the build doesn't have access to the generated objects.inv the gives the inventory of objects for intersphinx linking. Without it, you can't do the intersphinx mapping.

I am not sure if it would be possible, but maybe if you also copy the objects.inv over as well. It usually goes in the same folder as your index.html file, which is usually in the created _build directory in sphinx, but that directory isn't there, so if you all did do this, maybe where index.html is, so in the api folder in the gh_pages branch.

See related Botorch issue pytorch/botorch#1464

[pcanaran]

Hi @madeline-scyphers, thank you for reaching out. We will review this and get back to you. There may be some delay this week and next.

Some questions:

• If we were to change the processing as you described (i.e. copy over objects.inv file), what would be a good way to validate that it would work for your use case?
• What is the project you are linking from? Do you have any examples of how the linking works from your project to others?

[madeline-scyphers]

@pcanaran

Thanks!

1. Instructions to validate can be found here at the bottom. There is a command line instructions. It should look something like this

    python -m sphinx.ext.intersphinx https://ax.dev/api/objects.inv 

   or

    python -m sphinx.ext.intersphinx https://ax.dev/objects.inv 

   depending on where the objects.inv is.

2. https://github.com/madeline-scyphers/boa is the project. Has in the intersphinx section one intersphinx linking. On this docs update branch there are more examples

[Balandat]

Not an expert on this, but we move some of the sphinx build files to the static site dir here: https://github.com/facebook/Ax/blob/main/scripts/make_docs.sh#L97-L101

Presumably we could do the same for the objects.inv as well?

[madeline-scyphers]

Yeah, that might work. I didn't read through all of the workflow to see what happened to the static files later, and I noticed that on the gh_pages branch there isn't a website folder, so I am not sure what other steps happen along the way. But that might be all that you need to do.

with the command

python -m sphinx.ext.intersphinx path/to/objects.inv

you can pass it a local path instead of a url, so you might be able to test it with you post build script and making sure the objects.inv survives. But that only tests part of it, since I am not sure what all you all do to the sphinx static that could break things. But hopefully that should work.

[pcanaran]

@madeline-scyphers Unfortunately we didn't have a chance to get to this. I added it to our wishlist tracking issue #566. Closing this one as we have tracking there. In the mean time if you prefer you can also send a PR instead. Thank you.