The link in the doc[1] is not rendering properly,
because the method `textual.app.App.compose`
is ignored in the doc in the filter[2]. This commit
overrides the filter in the app.md file, generating
the doc for the "protocol" method and fixing the
link rendering in the guide.
[1]: https://textual.textualize.io/guide/app/#composing
[2]: textual/mkdocs-common.yml
Fix#3141
* Hide some members from the public docs.
See relevant issue: #3076.
Some methods need to be implemented to make the widget work but the user doesn't really care about them. For that matter, we can hide them from the public documentation.
* Use private handler to hide from docs.
Related comments: https://github.com/Textualize/textual/pull/3080#issuecomment-1671129733
It looks like mkdocstrings will fail out if it can't download the inv files.
Unless there's a setting where you can tell it "try, but if you can't grab
them just don't try and create links" the approach here seems reasonable and
has the same effect.
https://github.com/Textualize/textual/issues/2629#issuecomment-1566672594
for reference.
* Change the title of some widget references to their class names
The widget reference index had a slight mixture of widget title styles, some
being their class name, others being "written English" type titles. This
settles on the titles always being the class name.
* Add a link to the ContentSwitcher to the widget gallery
No screenshot for this, on purpose. By definition this widget isn't visible,
except via other widgets that it's enclosing and handling.
* Have mkdocs watch the main nav file
* Mark the content switcher off the roadmap
I got a bit carried away with what to watch, and it looks like the mkdocs
watch plugin doesn't much care for watching for files that don't exist but
may.
When I made the changes to documentation generation I split up the then
single mkdocs configuration file. It looks like the reloader for mkdocs
always watches its configuration file, bit *only* the one that was loaded in
the first place, not any that are inherited from.
So this change adds all of the mkdocs yml files to the watch list to ensure
that any change causes the documentation server to reload.
Most useful if you're adding new files to the navigation.
All through our docs there are mentions of Python types and also Rich types.
This change will make the vast majority of mentions of them into actual
links that people can follow. So now, for example, when someone sees a
method that returns a `Style`, they can click on it and see what a `Style`
actually is.
With #631 in mind, start by moving the vast bulk of the documentation
configuration into a "common" file, and just keep the `nav` in the main
configuration file. The thinking here is that I want two entry points -- one
for building the full docs for the Textual website, and one for building a
local version of the docs.
Because mkdocs doesn't allow for inheriting a configuration and also
splicing into the `nav`, we'll be looking to duplicate the `nav` for now --
this will likely change eventually as that'll be a maintenance overhead that
we don't really want (will likely look at templating it or something). For
now though, let's look at the best way of splitting things up and seeing how
we can generate two different versions of the docs.
