Skip to content

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

@bitprophet

Description

@bitprophet

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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions