Whitespace stripped with numpy style causes trouble

[luke321321]

Part of the inheritance merging (for numpy style) involves stripping as much whitespace as possible. This is expected behaviour from the docstrings

custom_inherit/src/custom_inherit/_doc_parse_tools/numpy_parse_tools.py

Lines 142 to 143 in 7e08197

	Any whitespace that can be uniformly removed from a docstring's second line and onwards is
	removed. Sections will be separated by a single blank line.

and the tests

custom_inherit/tests/inheritance_test.py

Lines 79 to 80 in 7e08197

	GrandChild.__doc__
	== "Grand Child.\n\nMethods\n-------\nblah : does not much\nmeth: does something\n\nNotes\n-----\nBlah"

However, from the example README.md it's not expected (I've taken the liberty to shorten the example):

  """Method description

      Parameters
      ----------
      x: int
         blah-x
       ..."""

As this will be changed to

"Method description.\n\nParameters\n----------\nx: int\n blahx\n..."

However, this causes some trouble with other tools which use the whitespace differentiate between the parameter name and description to parse the docstrings. For instance, the parser in mkdocstrings and pytkdocs can no longer function correctly with the whitespace stripped.

Would the behaviour be able to be changed to keep the indentation? To a user this isn't expected from reading the package documentation or by assuming how it will behave.

I believe it might not be too hard a change to make but don't know this package well enough to be certain. I'm happy to make a PR if this is agreeable and you point me in the direction of where would be a good place to start

[rsokl]

I would be open to accepting this change, although it strikes me as a bit odd that the parsers you mention are sensitive to this extra, leading white space. It feels like they should be a bit more robust; that being said, I am not too familiar with them.

I do not think that this will be a trivial change, since you will need to identify the proper uniform indentation level to use when merging the docstrings, and yet "preserve" the whitespace.

cleandoc is used to strip the whitespace throughout custom-inherit's merge strategies. Here are all of the places where it is used: https://github.com/rsokl/custom_inherit/search?q=cleandoc

[pawamoy]

It's not odd at all in fact! These leading spaces are very important to distinguish between continuation lines of the current item, and the next item or block 🙂