Document custom types used and actually show their definition

[rodrigogiraoserrao]

I think we should document, perhaps in the API page, the custom types we use for things that are already documented.

For example, App.CSS_PATH shows up in the docs and is typed as CSSPathType, and the type itself is pretty much all the documentation needed for App.CSS_PATH.
However, CSSPathType isn't documented.

In my opinion, we chould/should document these custom types in the module they are defined in, or they should all be collected in a “Types” API page, for example.

Note: I spent some time trying to do this for a single type (CSSPathType) and I managed to put it in a separate API page.
However, I wasn't getting two important things:

1. The signature of App.CSS_PATH wasn't linking to CSSPathType.
2. I didn't manage to have CSSPathType show its signature, which is what I really wanted to have documented.

[willmcgugan]

I think the most straightforward solution would be to cover it in the docstrings. We do seem to be missing docstrings for CSS_PATH.

[rodrigogiraoserrao]

So, to clarify, you are suggesting that the docstring for CSS_PATH mentions and links to CSSPathType, for example?

[willmcgugan]

Yeah, if we can't somehow expand the CSSPathType then we could just say it can be a string, list of strings, or None.

[rodrigogiraoserrao]

Ok. I'll see what I can do.

[rodrigogiraoserrao]

Ok, I can correctly export useful type aliases and I can have the docs cross-reference them automatically when they show up in signatures. (Thanks, Dave, for the work in #2287!)

However, if you show a type alias in the docs, it won't expand its definition, even if you set the option show_source: true.
Sadly, this is probably the most important step of all!

So, do I manually add this duplicated info to the docstrings of those type aliases?
Do we create a small mkdocs/mkdocstrings plugin that handles this?

[willmcgugan]

What happens if we use the type in the docstring? i.e. something like this?

CSS_PATH = ""
"""str | list[str] | None: Path to css files, or a list of paths."""

[rodrigogiraoserrao]

That's fine and it'll show up but it's duplicated...
And it may look extra confusing when you add the missing typing to CSS_PATH which will also show up in the docs:

CSS_PATH: CSSPathType = ""
"""str | list[str] | None: Path to css files, or a list of paths."""

It wouldn't be terrible if we added it to the type alias:

CSSPathType = Union[
    str,
    PurePath,
    List[Union[str, PurePath]],
]
"""str | PurePath | List[str | PurePath]:  Valid types to set the path to CSS files."""

it is still duplication, but it is less duplication for type aliases that are used more than once.

[rodrigogiraoserrao]

I'll see what reply I get back from mkdocstrings/mkdocstrings#559

[github-actions]

Don't forget to star the repository!

Follow @textualizeio for Textual updates.