`show_doc` includes parsed sections from numpy docstrings

[rxavier]

Hi! I'm trying to port an existing codebase to nbdev and running into trouble with docstrings.

I'm not sure if I'm not following numpy style docstrings as strictly as I should and tripping over the parser in the process, or whether this is a legitimate bug, so here's a minimal example

I've included a method documented with docments which of course renders nicely.

#| export

class Test:
    """A class for testing
    
    Second line.
    
    Parameters
    ----------
    x
        First param
    y
        Second param in which I have added a /
        line break due to length
        
    Attributes
    ----------
    comb
        String combination of `x` and `y`
    """
    def __init__(self, x: str, y: Optional[int] = None):
        self.x = x
        self.y = y
        self.comb = x + str(y)
        
    def print(self,
              end: str = "-", # Line ending
              ) -> None: # No need to return anything, just print
        """Print attrs
        
        Print attrs 2
        """
        print(self.x, self.y, end=end)

1. A warning is printed in the rendered docs due to the Attributes section (/Users/rafxavier/Envs/poniard/lib/python3.8/site-packages/fastcore/docscrape.py:225: UserWarning: Unknown section Attributes else: warn(msg)). This is probably because fastcore/docscrape does not support it. Is this intentional? What about other standard numpy sections like Raises? The idea is to document these in notebook markdown?
2. Types are correctly pulled from the signature and descriptions from the docstings, and everything is rendered nicely in a table. However, a Parameters section with weird formatting is also included.

3. If the parameter description has a line break, it's not rendered correctly in the table

[seeM]

Thanks for the clear issue write-up! :) #969 fixes (1) redundant sections in numpy docstrings and (2) newlines in the parameters table. Here's what it looks like with the fix:

Is this intentional? What about other standard numpy sections like Raises? The idea is to document these in notebook markdown?

Our preferred approach is to document almost everything in separate code and markdown cells below the definition of your function/class. This gives the most flexibility, since you can write and execute arbitrary code, and you have access to any valid markdown (and even HTML/CSS/JS). Some of these examples can function as unit tests. For example, here's how I would document your example class:

...and here's how it gets rendered as documentation:

For documenting "raises", I would consider using fastcore.test.test_fail to demonstrate failure cases.

[rxavier]

Thank you for the quick fix @seeM!

I have to get used to nbdev's more flexible approach to documentation. In many ways I think it's superior but it takes a change of perspective.

[jph00]

@seeM should we add attributes etc to docscrape before we close this? I'll reopen this for now - feel free to close if you think it's not an issue.

[rxavier]

@jph00

@seeM should we add attributes etc to docscrape before we close this? I'll reopen this for now - feel free to close if you think it's not an issue.

If it's okay, I'll add my 2c: supporting the main numpy sections would reduce a lot of the friction for existing libraries to migrate to nbdev. Contributors could then slowly adopt nbdev's way of documenting, but with a working migration in place.

[jph00]

That's a good point @rxavier.

OTOH, the reason I didn't include support for those sections in the 1st place was because using them in nbdev is not really best practice use of nbdev.

Perhaps what we really need is to support them, but also print out a message mentioning that's there's better ways to do it in nbdev, with a link to a best practices authoring guide?

[seeM]

Good questions. I was initially hesitant because it meant supporting 15 possible sections each of which is also rendered in slightly different ways, which seemed like a lot to maintain, especially when putting everything in the docstring is the opposite of the recommended approach.

I do see the value in allowing people to slowly migrate over, though, so I do think it's worth investigating.

There are also open questions for nbdev-style docs, like whether we could/should have a parameter table for object attributes, raises, and "see also" blocks (this page from numpy docs demonstrates a few of these). These could also be documented in a best practices authoring guide.

[jph00]

Created an issue to track adding an appropriate warning - I think that might be the best next step
#981