[New Concept Exercise] : docstrings

[aldraco]

This issue describes how to implement the docstrings concept exercise for the Python track.

Getting started

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read up on the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercise and how they are structured?

Please also watch the following video:

• The Anatomy of a Concept Exercise.

Goal

This exercise should demonstrate and motivate the proper use of docstrings in Python, according to PEP 257.

Learning objectives

• What is a docstring?
• __doc__ dunder / magic attribute
• Student should implement a one-line docstring (e.g. for a function and/or method)
• Student should implement a multi-line docstring, properly formatted

Ideally, this exercise would have a pre-written module, which contains a class, which has several methods on it. The student should write the documentation for

• the module
• the class
• methods within the class

Since this is an automated exercise, there isn't a lot of room for discussion of the content of the docstrings, but we can check for its existence, formatting (a blank line between summary and paragraph, for example) and an approximate length that we feel is appropriate.

Out of scope

• Enforcing a specific docstring convention for styling (i.e. reST vs google's style guide).

The examples should probably be in reST since it's fairly prevalent, but the formatting here is more related to a specific implementation of a documentation parser, not a generalized understanding of what docstrings are and how they should be used.

• return types

Mentioning that return types can/should be documented is a good idea, but not necessary for the scope of this exercise, since it can also be covered more thoroughly by a typing exercise or similar.

Concepts

• docstrings

Prerequisites

• comments
• functions
• methods
• classes
• modules

Resources to refer to

https://www.python.org/dev/peps/pep-0257/ https://www.python.org/dev/peps/pep-0287/

https://docs.python-guide.org/writing/documentation/#docstrings-and-magic https://docs.python-guide.org/writing/documentation/#sphinx

Hints

The following should be explicilty tested for:

• a summary line
• a blank line between the summary and the larger docstring
• docstring should exist for the module, class, and methods

After

Now is a good time to think about introducing the student to the magic (and usefulness) of automated documentation generators, or exposing them to prevalent examples of them in the Python community.

Representer

?

Analyzer

?

Implementing

Tests should be written using unittest.TestCase, and the test file named docstrings_test.py.

Help

If you have any questions while implementing the exercise, please post the questions as comments in this issue.

[BethanyG]

We've added basic doctstrings to the basics exercise (see issue exercism/v3#1999 and related PR). Propose we change this into a concept exercise around docstring and doctest best practices, and formatting for documentation generator tools such as Sphinx. @cmccandless - thoughts?

[cmccandless]

Propose we change this into a concept exercise around docstring and doctest best practices

Agreed

and formatting for documentation generator tools such as Sphinx.

I think perhaps doctest and Sphinx are worth a mention in the after.md of such an exercise.

[BethanyG]

Putting this on hold until we can get the issue updated with new specs.

[github-actions[bot]]

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

[BethanyG]

I don't like you stalebot. Not even a little.

[BethanyG]

This needs more detail and a write-up under the new issue template. Closing for now until we can get to that.