Add pound colon #: parsing

[lwpiotr]

Hello,

Sphinx allows for documenting comments starting with "#:", above or just after the variable. I am not able to use such comments with Read the Docs autoapi, which is a shame. Would it be possible to add their handling to the package?

[astrojuanlu]

Also observing this in poliastro (thanks @humitos) poliastro/poliastro#1569

[klieret]

I also miss this feature a lot (the documentation of dataclasses, namedtuples etc. comes out empty when I use this syntax). I'm surprised this isn't provided by the napoleon sphinx extension (but perhaps sphinx-autoapi uses an independent parser...)

[klieret]

Hi! Do you have any plans to implement this in future releases?

[lwpiotr]

It would be really great if autoapi would support this Sphinx feature...

[chrisyeh96]

+1 on this! I would love to be able to document my class and instance variables with any of the 3 following styles, all of which are supported by sphinx.ext.autodoc

class MyClass:
    #: documentation
    var: int = 500

    var2: int = 500  #: documentation 2

    var3: int = 500
    """documentation 3"""

[bjlittle]

I'd ❤️ to see this feature land! 🙏

[comkieffer]

I'd be interested in implementing this.

@AWhetter Do you have an idea of where to get started on this?

[AWhetter]

The challenge with this is that the ast library that we use (astroid) does not support reading these documentation comments. Therefore we must either switch parsing library, or parse these comments out in AutoAPI and augment astroid's output with this information. Neither is easy.

We're already considering switching to Griffe for parsing (see #444). Griffe just so happens to have an extension for reading Sphinx comments (https://mkdocstrings.github.io/griffe/extensions/official/sphinx/). So if we determine Griffe to be a viable option, doing #444 may give us this for free!

If we do the parsing of these comments in AutoAPI, the place to do so would be in the parser (https://github.com/readthedocs/sphinx-autoapi/blob/9e6a70a8a964adff0e37a4b2f3f0340146279467/autoapi/_parser.py). The astroid nodes passed into the methods of the parser should have line numbers and column numbers available on them. Using those numbers it should be possible to read the source code (from somewhere but hopefully not by having to read the file a second time) back from that location to figure out the comment. With the comments read, it can edit the "doc" field of the dictionaries that it outputs.