Improve regex filter docstring and avoid compiling compiled regex

[Ambro17]

This PR improves the docstring of Filters.regex. Changed format to comply with the rest of the file, and specify that pattern can be either a string or a pattern object. Also avoids recompiling regex on regex instantiation.
Add test case and define Filter attribute so sphinx can show the proper message instead of the placeholder text

[jsmnbom]

All in all this looks like a good change! :D
I have a tiny nitpicky change I'd like you to make if you could, but other than that it LGTM.

[jsmnbom]

We actually have several filters that don't follow this pattern further down in the file.
As far as I can see we've set done it such that:

• All filters that don't need an input, name the class _Filter and init it as filter = _Filter()
• All filters that do need input, break PEP8 style and name the class filter - this also improves docs if I recall correctly.

[Ambro17]

You are right, i only saw the first filters so i asumed it was a distraction. Effectively, filters that expect an argument don't have the underscore prefix.
I'll change it today if i have time

[Ambro17]

Done, i'm not very familiar with sphinx so i would like to know if there's a way to build the docs to check the comment with the filter description (L212) is rendered as expected

[Bibo-Joshi]

Hey @Ambro17,
you can find a installation guide to sphinx here. Maybe you need to install spinx.ext.napoleon, sphinx_rtd_theme or other dependencies of conf.py.
You can build the docs by running make html in the docs directory. The HTML pages will be saved to docs/build/html, with index.html being the start page. The output of the make will also tell you, if dependencies are missing.
Hope this helps :)

[Ambro17]

@Bibo-Joshi Thanks! I managed to get it to look as i like. Not sure if you agree, here's a screenshot of how it looks now

[Bibo-Joshi]

Glad to help, @Ambro17!
A few minor suggestions:

• Note: is a keywoard in sphinx, so you can easily create those fancy Note-Boxes (like e.g. here).
• one can insert a code block with a double double-dot ::, which can help to make the text more readable. However, this surely is a question of taste.
• I think the filter method should not get a docstring. It seems to me that the type of docstring you inserted was only added to filters that don't need an input and are initialized as filter = _Filter(), e.g. here

    class _Regex(BaseFilter):
        """
        Filters updates by searching for an occurrence of ``pattern`` in the message text.
        The ``re.search`` function is used to determine whether an update should be filtered.
        
        Refer to the documentation of the ``re`` module for more information.
            
        Note:
            Does not allow passing groups or a groupdict like the ``RegexHandler`` yet,
            but this will probably be implemented in a future update, gradually phasing out the
            RegexHandler (See `Github Issue
            <https://github.com/python-telegram-bot/python-telegram-bot/issues/835/>`_).
        
        Examples:
            Use::
            
                MessageHandler(Filters.regex(r'help'), callback)
            
            to capture all messages that contain the word help. You can also use::

                MessageHandler(Filters.regex(re.compile(r'help', re.IGNORECASE), callback)
                
             if you want your pattern to be case insensitive. This approach is recommended
             if you need to specify flags on your pattern.
            
        Args:
            pattern (:obj:`str` | :obj:`Pattern`): The regex pattern.
        """

[Ambro17]

1. Added the proper spacing after Note: so it's rendedered nicely.
2. I checked this option and it seems cool but it sets a green background for the code. As all the other filters have the `` notation, i would prefer to mantain the same style over all filters, but tell me what you think
3. I agree that filters that don't receive arguments don't have the filter right now, but i'm not sure that was on purpose. As it currently renders a default message which is not correct or at least is confusing.
   
   The overriding of the filter method is done under the hood, users should not override the filter method, only build the filter with the desired regex.
   Personally i think that adding the filter behaviour for that case makes more sense than rendering the BaseFilter default message.
   

[jsmnbom]

Tested locally and seems good to me (CI is a bit broken right now)
Merging primarily to avoid conflicts with improving the regex filter for V12.
Thanks a lot for the PR :)