Use `yapf` to autoformat the Altair specifications in docs and examples

[mattijn]

What is your suggestion?

As said by @dangotbanned in #3544 (review):

yapf

@mattijn I haven't looked into this in much detail yet, but have some thoughts.

Since it has both a CLI and module interface - there may be multiple ways we could use it with the code block stuff I added in #3630.

I called out #3570 (comment) directly there, as this was the exact use case I had in mind.
If we went down that route, I'd still prefer to keep that separate from this PR.

I do want to reiterate that I feel more strongly towards some form of autoformatting for examples - than a specific style.
My preference is ruff, but within reason, I'm happy for this to be anything that others agree upon

Everybody prefers autoformatted Altair specifications in the docs and in the examples. Let’s hope we can finish this discussion using the described approach🙏

---

Adapted from #3630 (comment)

altair/sphinxext/code_ref.py

Line 243 in ed40320

class CodeRefDirective(SphinxDirective):

The addition of CodeRefDirective allows directly referencing the contents of a function in the docs.

There is also some interesting stuff in https://github.com/vega/altair/blob/main/tools/codemod.py that can be adapted to support this use case.
The short explanation is this supports rewriting & reformatting code to be used elsewhere.
So this would have the benefit of writing in the same style as the rest of altair code, but support autoformatting for a possibly different style if agreed upon in #3519.

More generally though, a move towards writing code blocks in .py vs .rst has other benefits from a maintenance perspective:

• Code reusability
• Code blocks updating in response to IDE refactoring
• Clearer diffs during review
• Full access to tools like ruff, mypy to ensure code quality

Have you considered any alternative solutions?

ruff it. ruff also provides autoformatting, but the proposed style by ruff deviates a bit from manually written specifications (See thread).

There is also a second alternative using ruff, which was mentioned in #3570 (reply in thread)

It may be helpful to compare the effect each tool/config has on a sample of the examples.

Note

Edited by @dangotbanned

[dangotbanned]

Formatting User Guide

This would require some decision on the Deferred item in #3630

What I imagined there would be similar to polars/docs/source/src.
They use mkdocs, so ignore that part, but the idea of having a parallel hierarchy to the .rst files.

Below is one current usage of the directive:

altair/doc/user_guide/customization.rst

Lines 848 to 850 in ed40320

	.. altair-code-ref:: tests.altair_theme_test.alt_theme_test
	:fold:
	:summary: Show Vega-Altair Theme Test code

Which is more generally:

.. altair-code-ref:: package.module.*.function

So if we moved more code to .py files and structured the filesystem, it could look like:

.. altair-code-ref:: doc.src.user_guide.customization.alt_theme_test

Maybe worth adding an option for the doc.src.user_guide prefix?

.. altair-code-ref:: customization.alt_theme_test
    :user_guide:

I'd still prefer not to use relative imports, but this would be applicable for almost every code block