Rework docstrings to improve generated API docs #81
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
meshy
commented
Oct 7, 2025
src/django_subatomic/db.py
Outdated
Comment on lines
62
to
65
| Note: | ||
| This has a bit of a clunky name. This is a deliberate attempt to | ||
| discourage its use. It reflects that using this function is a | ||
| bit of a clunky thing to do. |
Collaborator
Author
There was a problem hiding this comment.
Note: This is lifted from other internal docs. There's probably a better way of putting this. Suggestions welcome.
Collaborator
Author
There was a problem hiding this comment.
I've gone with:
Note:
This has a bit of a clunky name. This is a deliberate attempt to
- discourage its use. It reflects that using this function is a
- bit of a clunky thing to do.
+ discourage its use. It acts as a code-smell to highlight that places
+ which use it may need further work to achieve full control over how
+ transactions are managed.
meshy
commented
Oct 7, 2025
LilyFirefly
approved these changes
Oct 7, 2025
meshy
force-pushed
the
meshy/docs/docstrings
branch
from
e997ff7 to
6c3e838
Compare
This new structure causes these blocks to be rendered in admonitions in the generated docs, and renders references to related functions as links.
This will be especially useful when linking to settings pages from docstrings.
This makes it read consistently with the other docstrings in this file, separates comments on rolling back from those on raising errors, and links to docs on a related setting.
These notes are for internal use, but the docstrings are now used to generate public API docs.
meshy
force-pushed
the
meshy/docs/docstrings
branch
from
6c3e838 to
75242e4
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Until now the docstrings have prioritised people reading the code. Now that we generate API docs from them, it's sensible to reformat them so that they make nicer docs.