Working with InterSphinx

[Tristan Croll]

(Hope I'm asking the right person!)

I'm finally getting around to seriously documenting ISOLDE's API (now that it's settled to the point where that's a worthwhile endeavour). It would be great to be able to use InterSphinx to automatically link references to ChimeraX classes back to the ChimeraX documentation, but I'm struggling to make that work.

I've added sphinx.ext.intersphinx to my Sphinx conf.py, and

intersphinx_mapping = {
    'chimerax': ('http://preview.cgl.ucsf.edu/chimerax/docs/devel', None),
}

... which triggers the Sphinx build to correctly download objects.inv, but that's where I'm stuck. Including a reference to e.g.

:py:class:`chimerax.Atom`

... which *should* just work according to the intersphinx docs, doesn't find a way to link through (nor does chimerax.atomic.Atom or chimerax.core.atomic.Atom).

[pett]

Conrad is the current guru for this.

[Conrad Huang]

This is actually one of the things we want to address for 0.7. The stuff under docs/devel include tutorials that have code examples and links into the class reference documentation, all generated using Sphinx. However, I don't think that's where bundle documentation ought to go, except maybe the "almost core" ones like chimerax.ui or chimerax.atomic. I'll send updates as we explore the options.

[Tristan Croll]

Bumping this to ask how it's going, and to add that it would also be *really* nice to have an option to rebuild the documentation during bundle building. Due to the way Sphinx works, currently I have to install my latest build, manually run ChimeraX -m sphinx ... to rebuild the documentation, then rebuild the wheel file.