Link rcParams role to docs #11448

timhoffm · 2018-06-16T17:21:48Z

PR Summary

Follow up to #10226. This turns the text generated by the :rc: role into a link to the rc documentation.

Note: I'm no expert in docutils and it's really difficult to find good documentation. There generation of the refuri feels a bit clumsy, because I have to build the final url. Naturally, one would like to have some function label_to_uri('matplotlib-rcparams') but I couldn't find something like that. The downside is that we rely on a hard coded file structure, but I can live with that (We're not likely to change that often).

anntzer · 2018-06-17T08:05:29Z

Would setting refname instead of refuri (set it to whatever you'd use in rst to generate the link, minus the final underscore) work? (I think that may be handled at the transform stage, http://docutils.sourceforge.net/docs/dev/hacking.html#transforming-the-document)

anntzer · 2018-06-17T08:11:39Z

Minor point, possibly just an issue to open with sphinx/docutils (although we may get away with applying our own styling, but I'd rather get the issue fixed upstream): https://10444-1385122-gh.circle-artifacts.com/0/home/circleci/project/doc/build/html/api/_as_gen/matplotlib.axes.Axes.errorbar.html#matplotlib.axes.Axes.errorbar (see errorbar.capsize rc) uses curly quotes for the literal+link, whereas the previous version at https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.errorbar.html#matplotlib.axes.Axes.errorbar uses straight quotes; the latter seems better.
Or perhaps this is just a matter of putting the literal in the reference rather than the other way round?

timhoffm · 2018-06-17T14:30:27Z

Would setting refname instead of refuri work?

Only partially. It works for files in api/_as_gen. For files directly below api I get WARNING: Unknown target name: "matplotlib-rcparams" and the role appears literally in the html as a non-working link:

timhoffm · 2018-06-17T14:40:23Z

Curly quotes:

They are replaced by nodes.reference no matter of the nesting order with nodes.literal. Also, if you put a literal node into a reference node, the iteral formatting is not applied.

For now, the present solution is as good as I can get this (an alternative would only be a raw node).

anntzer · 2018-06-17T22:05:00Z

doc/_static/mpl.css

@@ -23,6 +23,14 @@ a {
    text-decoration: none;
 }

+a.rcparams {


Is is really worth it using a different styling (or even a different class)?
I think the normal orange would probably actually look better.

If we want to use styling, a class is the cleanest way.

To me, the original orange looked a bit too distracting. Can add a screenshot later.

Just for comparison. I still prefer the darker links for the rcParams. But I'm not dogmatic about this if the majority has another opinion.

Same color as regular links

Darker links

Let's see what others think, then.

👍 opinions welcome

I'm not sure why it should be distinct. Every other link in the docs, including normal url links, are the same orange.

anntzer · 2018-06-17T22:05:16Z

doc/sphinxext/custom_roles.py

+              'tutorials/introductory/customizing.html#matplotlib-rcparams')
+
+    ref = nodes.reference(rawtext, rendered, refuri=refuri,
+                          classes=['rcparams'])


would perhaps not bother with the separate class

Doesn't harm. And makes it easier to adapt the style of the link if desired now or later (e.g. it would also be possible not to have a literal node nested and instead style the font-family of the link).

(that comment basically just applies if we decide not to style rcs differently from normal links)

anntzer · 2018-06-17T22:05:33Z

doc/sphinxext/custom_roles.py

+    rel_source = inliner.document.attributes['source'].split('/doc/', 1)[1]
+    levels = rel_source.count('/')
+    refuri = ('../' * levels +
+              'tutorials/introductory/customizing.html#matplotlib-rcparams')


use an absolute link? ("/tutorials/...")

when trying this locally, sphinx links to file:///tutorials/introductory/customizing.html#matplotlib-rcparams

Perhaps set refid instead of refuri? (just throwing some ideas around -- but somewhere docutils does have the ability to do this, so we just need to find the right way to trigger it...)

Nope. refid='matplotlib-rcparams' just links to the local anchor #matplotlib-rcparams.

I don't have the time to scan through the docutils docs and try out various stuff. I've posted the question to stackoverflow. If there is no hint from there, I'd leave it at that.

(I don't think this needs to be resolved to merge this PR -- it's quite unimportant. The only remaining point for me is about the styling.)

timhoffm · 2018-06-20T20:41:10Z

Removed the css class and special highlighting for the link. It now appears as a regular link.

timhoffm · 2018-06-20T21:40:17Z

Concerning curly quotes: This is controlled via the smartquotes option.

Maybe, nodes.reference() applies them, because it does not know that it will be wrapped in nodes.literal(). I don't know if there is a way to locally deactivate this.

anntzer

Some possible further improvements, but that's clearly a step in the right direction and can be merged as is.

timhoffm added the Documentation label Jun 16, 2018

anntzer reviewed Jun 17, 2018

View reviewed changes

timhoffm force-pushed the rcparams-link branch from c44e030 to 49213f0 Compare June 20, 2018 20:40

Link rcParams role to docs

1af7495

timhoffm force-pushed the rcparams-link branch from 49213f0 to 1af7495 Compare June 20, 2018 21:02

anntzer approved these changes Jun 21, 2018

View reviewed changes

jklymak merged commit 0baeca9 into matplotlib:master Jun 21, 2018

timhoffm deleted the rcparams-link branch June 22, 2018 00:26

QuLogic added this to the v3.0.0 milestone Nov 27, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Link rcParams role to docs #11448

Link rcParams role to docs #11448

timhoffm commented Jun 16, 2018 •

edited

Loading

anntzer commented Jun 17, 2018

anntzer commented Jun 17, 2018

timhoffm commented Jun 17, 2018 •

edited

Loading

timhoffm commented Jun 17, 2018

anntzer Jun 17, 2018

timhoffm Jun 18, 2018

timhoffm Jun 18, 2018

anntzer Jun 19, 2018

timhoffm Jun 19, 2018

jklymak Jun 19, 2018

anntzer Jun 17, 2018

timhoffm Jun 18, 2018 •

edited

Loading

anntzer Jun 18, 2018

anntzer Jun 17, 2018

timhoffm Jun 18, 2018

anntzer Jun 19, 2018

timhoffm Jun 19, 2018

anntzer Jun 19, 2018

timhoffm commented Jun 20, 2018

timhoffm commented Jun 20, 2018

anntzer left a comment •

edited

Loading

Link rcParams role to docs #11448

Link rcParams role to docs #11448

Conversation

timhoffm commented Jun 16, 2018 • edited Loading

PR Summary

anntzer commented Jun 17, 2018

anntzer commented Jun 17, 2018

timhoffm commented Jun 17, 2018 • edited Loading

timhoffm commented Jun 17, 2018

Curly quotes:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Same color as regular links

Darker links

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm Jun 18, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

timhoffm commented Jun 20, 2018

timhoffm commented Jun 20, 2018

anntzer left a comment • edited Loading

Choose a reason for hiding this comment

timhoffm commented Jun 16, 2018 •

edited

Loading

timhoffm commented Jun 17, 2018 •

edited

Loading

timhoffm Jun 18, 2018 •

edited

Loading

anntzer left a comment •

edited

Loading