Tracking: Documentation

[CraftSpider]

• [ ] Add doc-blocks to functions
• [ ] Add doc-blocks to classes
• [x] Add doc-blocks to files (#47)
• [ ] Add tutorials
  • [x] Getting Started (#47)
  • [x] Making a fixture (#47)
  • [ ] Advanced Topics?
• [ ] Add contributing advice/guidelines
  • [ ] Where things go
  • [ ] Architecture and state
• [ ] Improve style
  • [ ] Spacing between functions (#62)
  • [ ] Better visual weighting for async/def vs name, and parameters vs their type hints.

[Sergeileduc]

Hi !

I thought I could begin to help, with adding docstrings to funcions and stuffs.

There's several docstring formats, I don't know which one you prefer ?

In order to be consistent, It would be great to agree (well, obviously, you choose) on a docstring format, to be consistent.

(in VScode, I use "Python Docstring Generator" by Nils Werner)

Knowing that whichever you choose, you can still generate your doc with sphinx (even if you don't choose Sphinx format, which is ugly (you'll just have to use an extension, like sphinx.ext.napoleon))

With Google format :

def make_member(user, guild, nick=None, roles=None):
    """[summary]

    Args:
        user ([type]): [description]
        guild ([type]): [description]
        nick ([type], optional): [description]. Defaults to None.
        roles ([type], optional): [description]. Defaults to None.

    Returns:
        [type]: [description]
    """

Sphynx format :

def make_member(user, guild, nick=None, roles=None):
    """[summary]

    :param user: [description]
    :type user: [type]
    :param guild: [description]
    :type guild: [type]
    :param nick: [description], defaults to None
    :type nick: [type], optional
    :param roles: [description], defaults to None
    :type roles: [type], optional
    :return: [description]
    :rtype: [type]
    """

Numpy format :

def make_member(user, guild, nick=None, roles=None):
    """[summary]

    Parameters
    ----------
    user : [type]
        [description]
    guild : [type]
        [description]
    nick : [type], optional
        [description], by default None
    roles : [type], optional
        [description], by default None

    Returns
    -------
    [type]
        [description]
    """

(if you allready know all that, I sincerely apologize, I didn't want to be rude)

[bravosierra99]

I've been slammed in and gone, but should be available some this week unless my wife has her kid. I know Rune and I both use Pycharm, and so tend to stick with their docstring. It seems closest to sphynx but obviously he is using the stub files for typing, so the type lines may be unnecessary?

[JayDwee]

Would be good if Documentation progression could be restarted 🙂 (Personally I recommend reStructuredText/ Sphynx format)

[CraftSpider]

Personally, I prefer to use a more minimal form of sphynx, relying on type hints instead of :type:. This works well with readthedocs, as the signature is already included so types in description are redundant.

def foo(a: int):
    """
        Summary goes here

        :param a: A blah blah for doing blah.
        :return: The result of blahing a
    """

[bravosierra99]

^

On Mon, May 17, 2021 at 7:42 PM Rune Tynan @.***> wrote:

Personally, I prefer to use a more minimal form of sphynx, relying on type hints instead of :type:. This works well with readthedocs, as the signature is already included so types in description are redundant.

def foo(a: int): """ Summary goes here :param a: A blah blah for doing blah. :return: The result of blahing a """

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/CraftSpider/dpytest/issues/25#issuecomment-842714669, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACD4QEMXHMYXGXR4DULNAH3TOGSVZANCNFSM4OW4QFMA .

--

Respectfully, Ben Smith