New Option: Configurable RST Substitutions

[andthum]

Related to Issues #7 and #10 and PR #16.

As bskinn explained in #10, RST allows the definition of substition sequences. Commonly used substitutions can be put into rst_epilog (or rst_prolog) of Sphinx' conf.py file. However, RST does not know about these definitions in conf.py and thus flake8 throws an RST305 Undefined substitution referenced: "XXX" error.

You could add RST305 to the list of ignored error codes or ignore it via flake8's per-file-igonres, like bskinn did. However these ways of ignoring the error code are quite coarse and you would not be warned if you indeed referenced an undefined substitution in one of the files.

Therefore, I suggest to add a config option rst-substitutions where users can enter self-defined substitutions to suppress error code RST305, similar to rst-directives and rst-roles introduced in #16.

[peterjc]

This sounds reasonable.

Note to self: If we switch the backend to rstcheck (now that the v6 API changes are done), that has options for this (and roles and directives) which we should be able to use rather than silencing errors (available at the command line and probably via Python too).

[andthum]

Glad to hear that you find it reasonable.

I hope I did everything correctly. I'm not sure how to handle the Code Climate error.

[peterjc]

I'm not too bothered about the CodeClimate warning. We could combine the three if statements into a single if ... and ... and ...: return 0 but that would probably be less readable.

What I would like to see is at least one test case using the new functionality though, something like the roles and directives test in tests/test_all.py would be enough.

[andthum]

Just tell me if you want to have more test cases (now there is really only one test case) or if you want anything else to be done.

[peterjc]

That looks good, and worth calling this the v0.2.6 release 👍

[peterjc]

Released, thank you.

[andthum]

Thank you for accepting my PR and your fast respond 😉

[peterjc]

I forgot to ask, would you like to be acknowledged in the release notes (see previous examples)?

[andthum]

Oh, this would be kind. Yes, thank you!