More Sphinx 1.6 problems

[bitprophet]

Sort of a follow-on from #71, which prompted me to dig deeper into how we were not really compatible with Sphinx 1.5/1.6.

Sphinx 1.5 was just due to Python 2.6 being dropped, so we did that here too, and no problem.

Sphinx 1.6 made a lot of internal API changes that broke us. I fixed all the stuff that seems to pop up in our test suites, but there's a side channel - parsing the changelog 'in-process' for stuff like my release Invoke tasks (which need to answer questions about a project's changelog state.)

Specifically, something seems to be almost skipping Sphinx itself when rendering, leaving us with "I'm docutils and what is this???" errors like:

Well...clearly :doc: should freaking work in Sphinx-flavored RST! (It also complained about a :ref: that I temporarily commented out.)

[bitprophet]

Actually, I think this was probably still an issue beforehand, and this is yet another spot where it's more just log visibility due to changes in how Sphinx logs. When I tidy up the log muting some more, this goes away.

Especially given that the side channel use case doesn't currently care whether or not the inner bits of changelog entries render correctly or not (they are purely concerned with the overall data structures about release lines & which issues go where) this has already wasted way too much of my time to dig deeper.

[bitprophet]

Today continues to be shit. Not sure what I did wrong but this wasn't actually fixed. 🤦‍♂️

[bitprophet]

Quick brain dump:

• At the docutils level, Sphinx is simply never asking it to add_role the traditional Sphinx roles like doc, ref, etc etc.
• However it is calling add_role for things like manpage, program, and even any and pep.
• Seems like the start of the divergence is around Sphinx.setup_extension, or rather what it calls, which is sphinx.roles.setup().
• The actual content of sphinx.roles.setup is the same in both Sphinx 1.5 and 1.6, but it seems like the contents of the data it iterates over - specific_docroles - is different. (Some values within that structure, like any and pep, are [as noted above] still present in 1.6, so it's not as simple as the entire thing being moved elsewhere...)
• Still digging into what that structure is & why it's apparently different now.

[bitprophet]

Yea seems :doc: at least was moved into the 'Std' domain in 1.6 for some reason, implying that my hacky attempts to render on the fly are...missing basically any non-builtin domains? Figured that would've errored out for many more things in the past too (though, again, this may be muddied by the logging issue - perhaps this has been going on and I just need to try harder to nuke these warnings.)

The change on Sphinx's end, at least for doc, is sphinx-doc/sphinx@12d639873953847de31ec99742b42e50e89ed58c

[bitprophet]

Yea, ref isn't in here even in 1.5, implying that if I remove the warning muting temporarily, I should get warnings about "the fuck is :ref:" under Sphinx 1.5 too...and yes, that is indeed the case.

So I am back to "fuck it just make it shut up", so question is, why are some of these warnings solved by getLogger('sphinx').setLevel and others...not?

[bitprophet]

Seems these come out of docutils' Reporter, not clear why that's the case here but for a bunch of others they seemed to bubble up into Sphinx proper.

Even stranger, they're clearly 'ERROR' level, yet the display says 'WARNING'. Wat.

Dug some more and it might be hard to actually set this level ourselves (and it would also apparently apply pretty widely and perhaps mute other truly-error situations) so now I'm wondering if it would be easier to get sphinx loading all of its domains after all.

[bitprophet]

Welp, so, turns out I just needed with sphinx_domains(env): in my doctree bit. Applies to most/all Sphinx versions too. It...monkeypatches docutils. So no wonder I had a very hard time figuring out what the hell was going on... :sob: