feature for exmaple file, tldr file, test file or even link anotation

[Metal-Bat]

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

[kuyugama]

Why not just specify URL inside the docstring? For example Markdown or reStructuredText

variable: Annotated[
    str,
    Doc(
        "`The link <https://github.com/kuyugama/theproject>`_"
    )
]

[kuyugama]

This library is intended as easy way to document variables/parameters/attributes/returns. Not the functions itself. For functions/modules/classes you have docstrings.

Possibility to mark parameters as deprecated inside annotation would be great addition.

Mentioning code examples it would be great to store them inside docstring also. For example, implementing custom reStructuredText directive

.. examples::
    :file: ../examples/some_example.py

    .. code-block:: python

        from library import useful_func


        useful_func("os.system", "rm -rf /")

[Metal-Bat]

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

[kuyugama]

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

[Metal-Bat]

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

[kuyugama]

That's too much for an in-code documentation. For that you have other tools targeted specifically on the documentations

[tiangolo]

Thanks for the interest! But this would be out of the scope of this project, so I'll pass on this.

[Metal-Bat]

thanks