Use sphinx builtin only directive instead of custom one.

[timhoffm]

PR Summary

Switch from our custom .. htmlonly:: and .. latexonly:: directives to the sphinx builtin .. only:: html and .. only:: latex.

AFAICS they do exactly the same. So let's get rid of some proprietary stuff and just use plain sphinx.
Our directives are from mid 2008. Sphinx itself introduced that functionally just slightly later in Release 0.6 (Mar 24, 2009).

[dstansby]

Should we deprecate only_directives.py instead of just deleting it?

[timhoffm]

If we want to be very strict in our deprecation policy, yes.

However, the only use case for these would be in the documentation of downstream projects. Building documentation is happening pre-release, so they will notice and can simply replace the expressions. The only advantage of a deprecation would be that the downstream projects have a bit more time for the change. Given the timing (introduced mid 2008, superseeded early 2009 by sphinx directives), I question if anybody else uses our (undocumented) directives at all.

I would be practical here and dare removing it straight away. But if you feel a deprecation is better, I can add one.

[dstansby]

Yeah, I think I would be in favour of deprecating just in case, and then removing in 3.1.

[matthew-brett]

The problem with deprecation is that most doc builds are already pretty noisy in their warning output. I bet most people won't notice an extra deprecation warning.

[dstansby]

People might notice a deprecation changelog entry though? I'm not too bothered either way about deleting/deprecating, but either way this needs a changelog entry.

[matthew-brett]

I don't know about you, but I've never got my first warning of a deprecation from a changelog entry. If I see one, or I get an error, then I might go looking.

[jklymak]

Merged. If someone wants to get excited about adding a deprecation, thats fine, but I don't think the case is very strong.

[dstansby]

Can this get a changelog entry?

[tacaswell]

Downstream users of this included by day-job 😞