Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove version info from Werkzeug in the docs #60

Open
dawranliou opened this issue Jun 2, 2016 · 6 comments
Open

Remove version info from Werkzeug in the docs #60

dawranliou opened this issue Jun 2, 2016 · 6 comments
Labels

Comments

@dawranliou
Copy link

The following version information is coming from the Werkzeug docs: "New in version 0.6: The location can now be a unicode string that is encoded using the iri_to_uri() function." See http://flask.pocoo.org/docs/0.11/api/#flask.redirect.

There might be more of this kind of issue in the documentation. For this particular one, you can trace the code to docs/api.rst,:

.. autofunction:: redirect
@davidism
Copy link
Member

davidism commented Jun 4, 2016

@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.

@untitaker
Copy link
Contributor

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 davidism added the docs label Jun 1, 2017
@davidism
Copy link
Member

davidism commented Jun 9, 2017

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
Copy link

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
Copy link
Member

davidism commented Jun 9, 2017

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
Copy link
Member

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

5 participants