Reduce amount of RFC copy in functions, properties, modules and class docstrings

[niccokunzmann]

At the start, I thought it was good to copy in information of the RFC into different locations. That addresses the following problems.

• It is hard for developers to construct valid calendars when it comes to details. Putting the context into the places informs them.
• Sometimes, attributes influence other attributes or parameters. It is good to know about the side effects.
• Code affected by several RFC has parts of those copied together, so there is an overview.
• Having RFC text examples, we can more easily create code examples.

However, this approach does not solve all problems, and creates other problems.

• It duplicates existing documentation from the RFC.
• It doesn't document the implementation of the RFC in Python.
• It doesn't document what the class does, which is the purpose of Python docstrings.

General guidance

• Follow the Python docstrings style guide, especially Docstring structure.
• Sometimes you'll need to escape docstrings.
• See Docstring examples.
• It's strongly recommended that you build the documentation locally, and not attempt this through only the GitHub web editor. It will save you and the pull request reviewers a lot of time, effort, and frustration. Building locally gives you a live preview of the documentation while you edit it. You can also test usage examples automatically. See Build and check documentation for details.

Docstring sections

• The docstring's Summary should be a brief sentence. It shouldn't have a section heading.
• The docstring's Description should do the following. It shouldn't have a section heading.
  • Discuss RFCs that are implemented in the Python class or property.
  • Include links to the specific sections in the original RFC. See General cross-references for an example.
  • Highlight special cases, if any, for example, float can be one or many.
  • Refer to any related classes or properties. Examples:
    • vFloat is a single float, and vGeo is multiple floats.
    • RECURRENCE_ID is usually a DATE-TIME and must use the same value type as the DTSTART property in the same component.
  • Explicitly describe any constraints or requirements for classes or properties.
• The docstring's Attributes, Parameters, Returns, and Raises section headings might be automatically generated. If you build the documentation locally, you'll see how your edits affect the appearance of how it renders to HTML.
• The docstring's Example section should have either text examples from the RFC or usage examples of icalendar, such as instantiating an object from the class, and how to add, edit, or remove properties. Usage examples are tested automatically.

Property example

The following code is an example of a property declaration with a docstring for component categories.

categories_property = property(
    _get_categories,
    _set_categories,
    _del_categories,
    """This property defines the categories for a component.

IANA, non-standard, and language property parameters can be specified on
this property.

The property can be specified within "VEVENT", "VTODO", or "VJOURNAL"
calendar components. Since :rfc:`7986#section-5.6`, it can also be defined
on a "VCALENDAR" component.

This property can be used in icalendar through its Python attributes of :attr:`Event.categories <icalendar.cal.event.Event.categories>`, :attr:`Todo.categories <icalendar.cal.todo.Todo.categories>`, :attr:`Journal.categories <icalendar.cal.journal.Journal.categories>`, and :attr:`Calendar.categories <icalendar.cal.calendar.Calendar.categories>`.

This property is used to specify categories or subtypes of the calendar
component. The categories are useful to search for a calendar component of
a particular type and category. Within the "VEVENT", "VTODO", or "VJOURNAL"
calendar components, more than one category can be specified as a
COMMA-separated list of categories.

Note:
    At present, icalendar doesn't take the LANGUAGE parameter into account.

Parameters:
    categories(list[str]): A list of categories as strings.

Example:
    Create an event, add categories to it, print its ical representation,
    append another category, and finally compare the result
    against its expected value.

    ..  code-block:: pycon

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.categories = ["Work", "Meeting"]
        >>> print(event.to_ical())
        BEGIN:VEVENT
        CATEGORIES:Work,Meeting
        END:VEVENT
        >>> event.categories.append("Lecture")
        >>> event.categories == ["Work", "Meeting", "Lecture"]
        True

See also:
    :attr:`Component.concepts <icalendar.cal.component.Component.concepts>`

""",
)

Result

[stevepiercy]

@niccokunzmann please take a look at the edit of the issue description. I modified the original docstring to be more Pythonic and helpful. Please let me know.

[niccokunzmann]

This looks good.

My ideas:

(1) combine spec and links:

Somehow, this looks like duplication. Can they be merged in some way?
Rule: Link to the property when it exists instead of naming RFC components
Rule: Mention which RFC introduces which functionality.

The property can be specified within "VEVENT", "VTODO", or "VJOURNAL"
calendar components. Since :rfc:`7986#section-5.6`, it can also be defined
on a "VCALENDAR" component.

This property can be used in icalendar through its Python attributes of :attr:`Event.categories <icalendar.cal.event.Event.categories>`, :attr:`Todo.categories <icalendar.cal.todo.Todo.categories>`, :attr:`Journal.categories <icalendar.cal.journal.Journal.categories>`, and :attr:`Calendar.categories <icalendar.cal.calendar.Calendar.categories>`.

Like this or just the classes?

:attr:`categories` can be be specified within :attr:`Event.categories <icalendar.cal.event.Event.categories>`, :attr:`Todo.categories <icalendar.cal.todo.Todo.categories>`, :attr:`Journal.categories <icalendar.cal.journal.Journal.categories>`. Since :rfc:`7986#section-5.6`, it can also be defined within :attr:`Calendar.categories <icalendar.cal.calendar.Calendar.categories>`.

reorder

Also, a reorder would help me to see first why I would use it, then where (if) and then how, leading to what else to consider

This property defines the categories for a component. # one line

Description:
    This property is used to specify cate... # description

Parameters:
    IANA, non-standard, and language property parameters 

Compliance:
    :attr:`categories` can be be specified within ...

Example:
    ...

See also:
    ...

What do you think? I would let you do the edit above so that you can see both versions.

[stevepiercy]

I edited the description to remove most RFC language and make it more Pythonic. I think it's OK to use the RFC language as a starting point, provided the final product describes the icalendar implementation in Python. See example below. Another reason not to duplicate the RFCs is that, for example, 5545 doesn't mention 7986. So it implies you can't set categories as a comma-separated list on Calendar!😱

As far as a section heading for Description, that's a big nope. See PEP 257, Multi-line Docstrings:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.

Neither the summary line nor the description require section headings. Neither Description nor Compliance are supported section headings. Let's stick to what's supported, and put compliance in the description.

How does this work for you?

Example v2

categories_property = property(
    _get_categories,
    _set_categories,
    _del_categories,
    """This property defines the categories for a component.

The categories property is used to specify categories or subtypes of the
calendar component. The categories are useful to search for a calendar
component of a particular type and category.

Within the calendar components, specify categories as a list of strings.
You can get, set, and delete categories for a component.

This property can be used in icalendar through its Python attributes of:

-   :attr:`Calendar.categories <icalendar.cal.calendar.Calendar.categories>`
-   :attr:`Event.categories <icalendar.cal.event.Event.categories>`
-   :attr:`Journal.categories <icalendar.cal.journal.Journal.categories>`
-   :attr:`Todo.categories <icalendar.cal.todo.Todo.categories>`

The categories property for ``Event``, ``Journal``, and ``Todo`` complies with :rfc:`5545#section-3.8.1.2`, and for ``Calendar`` with :rfc:`7986#section-5.6`.

Note:
    At present, icalendar doesn't take the LANGUAGE parameter as defined in :rfc:`5545#section-3.2.10` into account.

Parameters:
    categories(list[str]): A list of categories as strings.

Example:
    Create an event, add categories to it, print its ical representation,
    append another category, and finally compare the result
    against its expected value.

    ..  code-block:: pycon

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.categories = ["Work", "Meeting"]
        >>> print(event.to_ical())
        BEGIN:VEVENT
        CATEGORIES:Work,Meeting
        END:VEVENT
        >>> event.categories.append("Lecture")
        >>> event.categories == ["Work", "Meeting", "Lecture"]
        True

See also:
    :attr:`Component.concepts <icalendar.cal.component.Component.concepts>`

""",
)