Linking to param types with intersphinx

[cblegare]

Hi there!

First, thank you a lot for this project!

I am documenting a class:

/**
 * Define a class that is extraordinarily nice.
 */
class NiceClass {
    /**
     * Information can come from the class docstring or this constructor too.
     *
     * @param {String} value A value.
     */
    constructor(value) {
        this.value = value;
    }

    /**
     * Configure some behavior to represent this as a string.
     *
     * @return {String} Something that looks like the usage of the constructor
     */
    repr() {
        return `NiceClass(${this.value})`;
    }
}

And I have built an objects.inv that provides reference for using intersphinx with the primitives at https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference.

It is configured as usual in my conf.py:

intersphinx_mapping = {
    "python": ("https://docs.python.org/3/", None),
    # ... others
    "mdn": ("https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/", "mdn.inv")
}

Alas! It can't find the parameter types!

This @param {String} generates the following warning:

index.js:./index.NiceClass(4):59: WARNING: js:func reference target not found: String

In my inventory, I have String as a js:class, not a js:function.

I can workaround that with a custom sphinx extension:

intersphinx_aliases = {
    ("js:function", "String"): ("js:class", "String"),
    ("js:function", "Object"): ("js:class", "Object"),
}


def add_intersphinx_aliases_to_inv(app):
    from sphinx.ext.intersphinx import InventoryAdapter
    inventories = InventoryAdapter(app.builder.env)

    for alias, target in app.config.intersphinx_aliases.items():
        alias_domain, alias_name = alias
        target_domain, target_name = target
        try:
            found = inventories.main_inventory[target_domain][target_name]
            try:
                inventories.main_inventory[alias_domain][alias_name] = found
            except KeyError as e:
                inventories.main_inventory[alias_domain] = {alias_name: found}
                continue
        except KeyError:
            print("missed :(")
            continue


def setup(app):
    app.add_config_value("intersphinx_aliases", {}, "env")
    app.connect("builder-inited", add_intersphinx_aliases_to_inv)

So, in your opinion, does this should be fixed in sphinx-js, or should I consider javascript classes also as javascript functions when generating the inventory?

[cblegare]

For reference, here is a plain text copy of the generated inventory
mdn.txt

[erikrose]

First of all, that is a pretty cool project, and I hope you succeed and turn it into something others can pull off the shelf. :-)

On your problem: sphinx-js doesn't actually have an opinion on whether String is a function or a class. It emits the RST field list :param String value: A value., and Sphinx proper takes it from there. Perhaps Sphinx itself is assuming it's a function? Though that would be a strange assumption for the type of an argument.

[cblegare]

Thank you for this information!

I'll track where that RST is emitted, track back to sphinx-js code and troubleshoot from there.

This is indeed a nice project. I'm trying to help lower the barrier of using Sphinx for colleagues.

See also related (not to this issue but to my project ;)) :

• idea: sphinx objects inventory shed bskinn/sphobjinv#148
• [idea] Explore creating synthetic intesphinx references for non-sphinx resources webknjaz/intersphinx-untangled#1

[erikrose]

You're welcome!

sphinx-js emits the relevant RST in renderers.py, in JsRenderer._fields(). I'd paste something like it emits into an RST doc, run Sphinx over it, and see if you have the same problem. I expect you'll end up making a patch to Sphinx itself, but, if you can fix it just by tweaking the RST, I'm happy to consider changes to sphinx-js's emissions.