Create a custom Sphinx extension to document configuration values with
a simplified syntax. It is based on the `confval` but takes less space
when rendered. The extension provides:
- A `conf` directive for documenting individual configuration values
with optional type and default parameters
- A `conf` role for cross-referencing configuration values
- Automatic formatting of default values in the signature
- A custom domain that handles indexing and cross-references
For example, if we have
.. conf:: search_limit
:default: 5
We refer to this configuration option with :conf:`plugins.discogs:search_limit`.
The extension is loaded by adding the docs/extensions directory to the
Python path and registering it in the Sphinx extensions list.
## Description
The current developer documentation feels somewhat cluttered due to
inline auto-generated API references for certain classes. To improve
readability and maintainability, this PR introduces a more streamlined
approach that aligns better with best practices observed in other PyData
ecosystem documentation.
Specifically, this PR:
- Adds a dedicated `api/` folder to the documentation structure.
- Moves all auto-generated references (classes, methods, etc.) to this
folder.
- Enables clean, concise linking to API elements from the narrative
documentation—without interrupting human-written content with large
autogenerated blocks.
This separation makes the documentation easier to navigate and maintain,
while still providing full API reference coverage where needed.
- [x] Documentation
- [x] Changelog
- Set static path and css file in Sphinx config.
- Codebox style to black/white
- Secondary color to beetroot red
- Inline code color to beetroot green
- Leave primary color (pydata teal), difficult to read with beetroot
green. Works well with beetroot red actually.
- Leave some notes on colors in beets.css for reference.
- Sticky Nnavigation (default but make sure)
- Top left area white, to fit with beets logo background
- Title "beets"
- Logo only false, we want to see title
- Version true, we want to see which beets version we are looking at
- Issue: The latter two are invisible, would require custom CSS!!!
This is a quickfix to get back the behaviour we previously had with the
readthedocs theme. There could be adjusted and fixed more, but postpone that
and do in a proper PR.
