Is ":#" type doc support *supposed* to work 'cause I sure wish it would...

[ssteinerx]

Problem Description

I am trying to document e.g. instance variables. Things that don't get regular triple quoted docstrings.

I know pdoc supports the rejected PEP-0224 doc format but I find it to be incredibly confusing to the point of unusability (for me).

...
  def __init__(self):
    """Init doc."""
    self.ivar1: str = "A default value... or is there more below?  Hard tellin'." 
    """This is just a triple-quoted string in space.  It is not at all obvious (to me) that it goes with ivar1"""

I much prefer the syntax supported by Sphinx Autodoc.

...
  def __init__(self):
    """Init doc."""
    self.ivar1: str = "Much better" #: This obviously goes with ivar1

The Sphinx Autodoc syntax occurs several times in the test suite in flavors_google.py and flavors_numpy.py but the strings never make it out of there except in the source code view.

Proposal

I would really like the option of using the Sphinx Autodoc syntax. I tried using the PEP-224 style and ended up putting it all into Sphinx Autodoc comments for when it works later ;-).

Alternatives

I've tried using the rejected PEP-224 syntax and agree with its rejection. It just doesn't scan right, and the opportunities for misinterpretation (concatenation) with default string values is real. The syntax detailed above is much better, in my opinion.

Additional context

There appears to have been an attempt at support at one time, but after reviewing it, it seems that it may have been in the source code of that other pdoc that I accidentally installed at one time. The Sphinx Autodoc syntax didn't work there at all, despite there being code that supposedly did support it. I have no idea if that code was part of the "fork" (read: heist), but deleted from here, or was added later, but there you have it.

[mhils]

It can probably be made work in doc_ast. Contributions welcome!

[ssteinerx]

It can probably be made work in doc_ast. Contributions welcome!

I'll take a look!

The only slightly annoying thing is that you might have to back up in the text to find the beginning of the class/ivar comment 'cause you can't really tell you have one until you hit the actual class/ivar declaration.

Should the occurrences in flavors_google and flavors_numpy tests detect them and fail if they don't? There are only a couple of instances of "#:" comments in each and they both look exactly like this:

        self.attr3 = param3  #: Doc comment *inline* with attribute

        #: list of str: Doc comment *before* attribute, with type specified
        self.attr4 = ['attr4']

There are a couple of other obvious-ish cases that will need tests:

        #: A comment that starts before the ivar, and then continues 
        self.attr23 = param23  #: with this doc comment *inline* with attribute

        #: list of str: Doc comment *before* attribute, with type specified
        self.attr24 = ['attr24']  # But not continued here
        #: This does *not* become part of `attr24`'s doc comment

I'm sure there are more, I'm just putting these here while I'm thinking about it ;-).

[mhils]

The only slightly annoying thing is that you might have to back up in the text to find the beginning of the class/ivar comment 'cause you can't really tell you have one until you hit the actual class/ivar declaration.

It's either solvable withast.parse or out of scope for pdoc.

The snapshot test are there to ensure that changes don't unintentionally change behavior. If we can easily support more stuff that's great, if we can't, then that's ok too. :)

[ssteinerx]

Unfortunately, the ast module just whizzes by all comments, doesn't store'em, doesn't track'em, just doesn't care about anything but actual "things to be translated" and officially sanctioned forms of annotation.

The obvious way to do this is with a super-simple preprocessor that takes "#:" comments, coagulates them, and repositions them as triple quoted strings below the documentee, then passes the preprocessed output to pdoc proper.

I don't see that pdoc really has a place to screw in such a thing, does it? It's not so much a plugin as "middleware", but I don't see an obvious hook.

[ssteinerx]

I give up. Since all of the actual object traversal is done in Jinja, it's virtually impossible to just switch out the output format. I was just trying to write a test to prove that I was doing the same things as Sphinx, and just getting a simple comparable text output for testing would have required duplicating a whole ton of Jinja code since there isn't a replaceable emitter in the render step. Without being able to test... So I stopped. Thanks for your help.