Remove version info from Werkzeug in the docs about pallets-sphinx-themes

[untitaker]

We should set a manual description for this function, and refer to Werkzeug docs (see intersphinx for that).

Another reason for a necessary rephrasing is that "return a WSGI application" is unnecessarily low-level for Flask's docs, and only appropriate for Werkzeug's.

[davidism]

@untitaker really not sure what to do here. Maybe there's a way to indicate the package as well as the version for externals we're re-documenting? Or disable the versions in those cases? This came up while looking at pallets/flask#1704.

[davidism]

Similar to how I wrote a plugin to collapse old version directives, maybe we can write a plugin that adds "Werkzeug version ...". That would be a lot more maintainable.

[tristanfisher]

I apologize if this is more general, but what level of technical detail is desired when writing Flask docs? I wouldn't consider mentioning WSGI to be low-level, but can understand if that's meant to be abstracted.

[davidism]

I don't have a particular problem with how the API docs read currently. If we need to simplify something that can be done at a later time.

[davidism]

I've started investigating this. It's going to be messy, but I think it's possible.

The sphinx.domains.changeset.VersionChange directive class controls the version messages. Unfortunately, it's not designed to be overridden, the sphinx.domains.changeset.versionlabels dict has strings that expect one %s substitution only, such as 'Changed in version %s'. This substitution is done a few lines in to the VersionChange.run method. We'll have to copy and modify the code for that method.

Once we do that, we can look up VersionChange.source in intersphinx. If it's not there, we can fall back to the source package name instead of the intersphinx title. If there's no intersphinx method for looking it up, we can fall back to scanning VersionChange.env.intersphinx_inventory.

Still need to investigate how we could determine if the source is the current package being documented, or an inherited method. That way we could exclude the package name if it's the current package. I think I'd actually prefer everything to have package names consistently though.