Changelog :option: rendering broke in Sphinx ~=1.3 #1454

Closed
bitprophet opened this Issue Apr 7, 2016 · 0 comments

Projects

None yet

1 participant

@bitprophet
Member

Problem

  • Since time immemorial we had optimistic pinning on our Sphinx dependency, e.g. as of 1.10 we were pinned to sphinx>=0.6
    • Between there and today's master, we moved it to be >=1.2
  • Sphinx 1.3 seems to have broken (among other things that affected me elsewhere :x but then again it added my theme as the default, so uh...can't complain?) intersphinx for :option: references, or similar: we get a bunch of errors like this one: https://travis-ci.org/fabric/fabric/jobs/107683225#L1196
    • Note that due to how we run Sphinx in Travis, it only shows the first one; when I run by hand I see one of those for every use of :option: in the changelog.
  • Confirmed that latest Sphinx 1.2.x doesn't error out.
    • However, it (and maybe this was always the behavior? Perhaps I never noticed after the www/doc split?) just does the usual "I dunno what this links to" thing where it makes the text bold+mono, and not a link.
    • That's still much better than erroring, though.

Solutions

  • Pinning to sphinx<1.3, I don't believe we require any features or fixes in Sphinx 1.3.x at this time.
  • Remove use of :option: in favor of regular monospace formatting (esp if it never did correctly link ever, this feels cleaner).

Other notes

This might be related to the upstream issue sphinx-doc/sphinx#2229 but I've not time to dig into it at the moment.

@bitprophet bitprophet added a commit that referenced this issue Apr 7, 2016
@bitprophet bitprophet Changelog re #1454 2fa6c1e
@bitprophet bitprophet added a commit that closed this issue Apr 7, 2016
@bitprophet bitprophet Replace :option: in changelog with regular monospace.
This might never have actually linked, and as of Sphinx 1.3 it actively
yields warnings (despite intersphinx working OK otherwise :()

Closes #1454
2713151
@bitprophet bitprophet closed this in 2713151 Apr 7, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment