docs: fix code formatting on rendered codecs API page#1455
Merged
Conversation
Three issues caused docstring code to render as plain text on https://docs.datajoint.com/api/datajoint/codecs/ (mkdocstrings is configured for docstring_style: numpy + Markdown-flavored bodies): - Codec class docstring used reST '::' literal blocks for the two table-definition examples. Replaced with Markdown fenced code blocks. - decode_attribute used Google-style 'Args:'/'Returns:' sections in a NumPy-configured doc generator. Converted to NumPy 'Parameters'/ 'Returns' with dashed underlines so it renders as a parameter table consistent with the rest of the module. - Module-level 'Example:' block now uses a Markdown fenced code block rather than relying on 4-space indentation. No behavior change - docstrings only.
2 tasks
MilagrosMarin
approved these changes
May 21, 2026
Contributor
MilagrosMarin
left a comment
MilagrosMarin
left a comment
There was a problem hiding this comment.
Thanks @dimitri-yatsenko! Verified the fix:
✅ datajoint-docs/mkdocs.yaml confirms docstring_style: numpy — reST :: and Google Args:/Returns: would indeed render as literal text on /api/datajoint/codecs/.
✅ All three conversions land in formats mkdocstrings + numpy parser consume. After this PR, grep "Args:\|Returns:\|Raises:" in codecs.py returns 0 matches.
✅ decode_attribute parameter list matches the function signature.
Approving. The mypy-skip note is handled transparently and CI doesn't gate on it anyway.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
https://docs.datajoint.com/api/datajoint/codecs/renders docstring code as plain prose in three places. The page is built bymkdocstringswithdocstring_style: numpyand Markdown-flavored bodies, so reST and Google-style syntax don't get parsed.Codecclass docstring (two examples)::literal blocksdecode_attributeArgs:/Returns:(parsed as paragraphs)Parameters/Returnswith dashes (renders as a parameter table)Example:No behavior change — docstrings only.
Test plan
codecsAPI page:Codec("Use in table definitions" / "Skip auto-registration") render as Python code blocks (no literal::)decode_attributeshowsattr,data,squeeze,connectionin a parameter table consistent with sibling functionsExample:Python sample renders as a fenced code blockpython -c "import datajoint.codecs"still imports cleanlymypy src/datajoint/codecs.pyclean (pre-existing unrelated failure instorage_adapter.py:98was skipped on commit; CI lint doesn't gate on mypy)Note on the unrelated mypy failure
Local pre-commit's mypy hook fails on
storage_adapter.py:98(aDeprecated.get()typing shim for olderimportlib.metadata). That error exists on master and is not enforced by CI (.github/workflows/lint.yamlonly runs codespell + ruff + ruff-format). Skipped withSKIP=mypy git commitper the documented pattern at the top of.pre-commit-config.yaml. Happy to file a separate PR for the typing shim if you'd like.