Explained import shortcuts in API design documentation#1281
Explained import shortcuts in API design documentation#1281stevepiercy wants to merge 4 commits intomainfrom
Conversation
Pull Request Test Coverage Report for Build 23378472901Details
💛 - Coveralls |
docs/reference/component-api.rst Outdated
| The preferred way to access their values is through lower case properties as described in :ref:`property-access`. | ||
| Advantages and disadvantages of the other approaches are discussed below. | ||
| | ||
| As a convenience, icalendar offers shortcuts to import its classes instead of using their fully qualified Python path. |
There was a problem hiding this comment.
The interface that should be used is from icalendar import X. That is the stable, public interface. From icalendar.Y import X is discouraged.
docs/reference/component-api.rst Outdated
| icalendar builds components and subcomponents. | ||
| It then adds, modifies, or removes properties to components and subcomponents, all within the RFC requirements. | ||
| This is done in the :doc:`prop <../reference/api/icalendar.prop>` module. |
There was a problem hiding this comment.
In a development reference, I would add that for resposibility clarity. This is not quite right though and I would remove this or clarify the intention of why this us needed.
There was a problem hiding this comment.
It's required because you can't understand properties without an understanding of components and subcomponents. Modified in b3127aa.
| | ||
| .. _import-shortcuts: | ||
| | ||
| Import shortcuts |
There was a problem hiding this comment.
While this section is right and still needs a focus on the !do not import from icalender subpackages! Then, it would be more suitable.in the design decisions document as it has nothing to do with the decisions around how components relate to the rfc.
how components relate and map to the rfcs is the focus of this document.
Import shortcuts are a Python API structuring for maintenance and development and stability.
There was a problem hiding this comment.
This document describes the API design. It's an explanation of the reasoning behind the choices made. This section is an explanation of both how and why you implemented shorter imports. Where else would it go, beside API design?
There was a problem hiding this comment.
Actually, this file doesn't belong in reference, but should be moved into a new section, explanation, to align with Diátaxis. It's not at all like a dictionary, glossary, or API reference, but more of an explanation of the design decisions. We have nothing that explains choices made at this time. What do you think? See https://diataxis.fr/reference-explanation/.
There was a problem hiding this comment.
Right! That makes total sense... It is an explanation
Documentation build overview
Show files changed (5 files in total): 📝 5 modified | ➕ 0 added | ➖ 0 deleted
|
| Let me know when I should have a look again! Thanks! |
3 participants
Closes #1161
Description
Explained import shortcuts in API design documentation.
Checklist
CHANGES.rst.📚 Documentation preview 📚: https://icalendar--1281.org.readthedocs.build/