Keep/delete_params features and optional docstring typehints

[michalk8]

Hi @Chilipp ,
thanks for making docrep, I find it really useful!
I have 3 small requests, all somewhat related to keep_params/ delete_params:

1. would it be possible to include alias argument (optional) to access the modified docstring? With some check if it's specified so that it doesn't overwrite existing keys.

d.keep_params("foo.parameters", "bar", "baz", "quux", alias="name")
# foo.parameters.name can be used instead of foo.parameters.bar|baz|quuux
d.keep_params("foo.parameters", "bar", "baz", "quux", alias=None)
# same as it is right now: foo.parameters.bar|baz|quuux
d.keep_params("foo.parameters", "bar", "baz", alias="name")
# would raise an error, alias "name" is already present

2. can keep_params and deleta_params be used as decorators? I'd like to keep things in place rather than invoking d.keep_params somewhere below the functions

@d.keep_parameters("foo.parameters", "bar")
@d.get_sections(base="foo", sections=["Parameters"])
def foo(bar, baz):
   """
   ...
   """
   pass

3. can typehints in the docstrings be made optional? I always use https://pypi.org/project/sphinx-autodoc-typehints/, so including them in the docstring is not necessary. However, not including them doesn't currently work with {keep,delete}_params.

def foo(bar: int, baz: str) -> None:
   """
   Quux.

   Parameters
   ----------
   bar
       The bar.
   baz
       The baz.
   """
   pass

I think 1. and 2. are fairly easy to adjust and I can make a PR for them.

As for 3., I somewhat naively though it might be as simple as modifying the relevant part of the regex from : to :? (or similar), however that's not the case, since some tests were failing (esp. the complex ones, where there was a mixture of keeping the annotations in the docstrings and omitting them [which is really discouraged]).
Maybe you have an idea how to best approach this?

[Chilipp]

hi @michalk8! Thanks for your input! As these are three feature requests, we should probably turn it into three separate issues.

1. would it be possible to include alias argument (optional) to access the modified docstring? With some check if it's specified so that it doesn't overwrite existing keys.

sure, why not. sounds reasonable to me.

2. can keep_params and deleta_params be used as decorators? I'd like to keep things in place rather than invoking d.keep_params somewhere below the functions

I understand your point. It's a bit awkward as the keep_params method would then just return a function that takes a callable does nothing, but I think that's ok.

3. can typehints in the docstrings be made optional? I always use https://pypi.org/project/sphinx-autodoc-typehints/, so including them in the docstring is not necessary. However, not including them doesn't currently work with {keep,delete}_params.

Sure, makes sense.

Maybe you have an idea how to best approach this?

I'd need to play around with the regex myself in order to solve this. It's indeed not that straight-forward. Alternatively, you could use the keep_types method, which should pretty much do what you'd like to see.