Pygithub: Docstrings problem

[RSully]

I'm using PyCharm for my development environment. I noticed that your code is rather well documented using docstrings. For example:

    def get_user(self, login=github.GithubObject.NotSet):
        """
        :calls: `GET /users/:user <http://developer.github.com/v3/users>`_ or `GET /user <http://developer.github.com/v3/users>`_
        :param login: string
        :rtype: :class:`github.NamedUser.NamedUser`
        """

However, this seems to not be the appropriate syntax, as my IDE still thinks the result could be Any. However, if I remove the :class:, it works properly. Could you send me any links that point to the :class: standard? I am going off of this.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[RSully]

There has been no change or answer. Do not auto-close.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[s-t-e-v-e-n-k]

It's hinting for our docs build -- see https://pygithub.readthedocs.io/en/latest/github_objects/Branch.html#github.Branch.Branch.get_required_status_checks, without the :class: it doesn't link the return type to the class.

[RSully]

Is it possible that during the 3 years since this issue was filed that the syntax has changed? More-so, I was more interested in finding a link to the documentation that shows it is necessary (not a link to where your docs show it in us), as - at least 3 years ago (to the day, no less!) - this syntax broke PyCharm. I imagine it must be standardized by now.

PS: I must say I am quite surprised to see any activity on this, me and stale bot have become quite good friends in the meantime 😊

[s-t-e-v-e-n-k]

It's possible the syntax has changed, but I can't find any documentation for Sphinx about it, and it works, so I'm loathe to change it. Also, it pre-dates my involvement in the project, so that goes double.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[RSully]

Do as you wish, but I'd encourage you to use a syntax that IDEs use to make things easier for contributors. I'm not sure if PyCharm supports this syntax or not now, but at the time it definitely did not.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[RSully]

Why don't other issues get marked as stale? Can we untag this as a question?

[s-t-e-v-e-n-k]

Ah ha, I found the documentation. https://www.sphinx-doc.org/en/1.5/domains.html#python-roles

Have you considered filing a bug against PyCharm for this?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[RSully]

From what I can tell, the :class: syntax is to create a link to a class within Sphinx documentation, not to actually designate a return type in :rtype:.

For example, I would expect this is how it would be used (not tested):

:rtype: github.NamedUser.NamedUser The rest of this text is describing the return type and may contain links to other classes like :class:`github.CommitStatus.CommitStatus` which would show up in the Sphinx documentation.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[Croydon]

Hi! This is my generic reply for every issue which is still relevant and is on the edge of getting closed by a stale bot.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.