-
Notifications
You must be signed in to change notification settings - Fork 8
First Check
- I added a very descriptive title here.
- I used the GitHub search to find a similar question and didn't find it.
- I already searched in Google "How to X with annotated-doc" and didn't find any information.
- I already read and followed all the tutorial in the docs and didn't find an answer.
- I already checked if it is not related to annotated-doc but to FastAPI or another specific project.
Example Code
from annotated_doc import Doc def hi( name: Annotated[ str, Doc( "Who to say hi to", tldr="doc.tld.hi.tldr", example="doc.example.example", online_example="https://doc.example.example", ), ], ) -> None: print(f"Hi, {name}!")
Description
i am thinking about a feature, maybe not the first one but a lazy load of example files or tldr or test files like having a point to that file or a link with no need for source code directly import but i think it is not the best way to handle it with string import path b.c files can change and break everything may be a validation along to it and then it will help easy navigation and learning in place
Operating System
Linux
Operating System Details
No response
Version
0
Python Version
3.12
Additional Context
No response
All reactions
Thanks for the interest! But this would be out of the scope of this project, so I'll pass on this.
Replies: 2 comments 8 replies
Why not just specify URL inside the docstring? For example Markdown or reStructuredText
variable: Annotated[ str, Doc( "`The link <https://github.com/kuyugama/theproject>`_" ) ]
All reactions
we actually can do the examples in docstring
""" >>> from library import useful_func >>> useful_func("os.system", "rm -rf /") """
all i am saying that docs in python can be way more rewarding and cleaner if we can separate the docs, examples and extra items in codes from the code itself
All reactions
All related to the function should be written inside function's docstring. The Doc was implement to provide a way to describe objects that don't have docstring - attributes/parameters/variables/returns. Other information you can put inside docstring. IMO, this is better than mentioning examples in annotations
All reactions
maybe i can not explain it well but my idea here is to make these the same thing for all project
no different for class, methods and attributes/parameters/variables/returns, why not all together in one place?
it makes all parts similar
make it way easier and simpler for developers to only fill data in Doc for every thing
i remember pydantic_settings made it super simple for reading from anything .env, files for sql or not
why not create a general-purpose doc tool that even can read from a toml file or a markdown file and can give type safe info about anything
it will make localization of a document super easy like you open a code base and all you need to do is set show me this localization or read only from this type files and Doc do it for you i hope i can describe my picture here
All reactions
That's too much for an in-code documentation. For that you have other tools targeted specifically on the documentations
All reactions
Great question—adding URLs directly to docstrings (Markdown/rst) like your example is excellent!
✅ Why it works:
Ties critical links (e.g., your GitHub repo) to the variable/parameter (no hunting for references).
Tools (Sphinx, IDEs) render these links as clickable hyperlinks in docs/hover text.
Aligns with Python’s "explicit is better than implicit" ethos.
📌 Small tweaks for scale:
Define repeated URLs as constants (avoid duplication if links change).
Agree on Markdown/rst with your team (no mixed syntax).
Only add URLs that add direct value (avoid clutter).
Your approach is spot-on—this is exactly how to make docstrings informative and tooling-friendly!
All reactions
Thanks for the interest! But this would be out of the scope of this project, so I'll pass on this.
All reactions
thanks