Check for docutils 0.18 and 0.19 and raise a helpful warning if it is installed

[choldgraf]

As we've discovered in #309, there is a nasty docutils bug in 0.18 and 0.19 that will break this extension in hidden ways (where people won't get an error, the page will just be wrong).

Since 0.20 isn't released yet, could we add a short-term quality of life fix to raise an error and give users guidance? I imagine a little function that triggers on config-inited and does the following:

1. Check if the user has specified configuration for this extension (meaning they intend to use it)
2. If so, check if docutils is 0.18 >= docutils version < 0.20
3. If so, then raise a Warning saying "This extension is not compatible with docutils versions 0.18 and 0.20, please pin docutils==0.17 and sphinx==5 until docutils 0.20 is released."

It could be a lightweight way to point people in the right direction if they hit this bug, given that getting the right versions installed will require a bit of searching.

[agoose77]

To add; I don't think we can fix this by updating the packaging metadata, as any current Python package installer with backsolve to find a version that doesn't have the pin. This would not be the desired behaviour. @choldgraf suggestion to error at run-time is the best that we can do here, and allows users to specify docutils < 0.18 in their configuration until a fix is released.

Let us know if we can do anything to help here.

[mcmtroffaes]

Yes, it's annoying that docutils still haven't released the fix. I agree with your analysis. I expect I will have time to give the extension a bit of love again after mid March. Feel free to make a PR in the meantime if you wish, and I'll do my best to review and merge.

[njzjz]

allows users to specify docutils < 0.18 in their configuration until a fix is released.

I think docutils != 0.18.*, !=0.19.* is better, so we do not need to change the configuration when 0.20 is released.

[mcmtroffaes]

This is now fixed in #330 which was just merged.