Add Vazirmatn (v33.003) support for Farsi

[sepehr-rs]

Adds Vazirmatn for Farsi builds. Vazirmatn is an open-source font licensed under the SIL Open Font License. Adding this to Farsi builds improves the readability and quality of the documentation.
I didn't touch the broader RTL fonts and kept it scoped to Farsi with :lang(fa). The font is bundled as a single variable WOFF2 file in static/fonts/, with its OFL.txt alongside.

With Vazirmatn:

Before:

Please let me know if any changes or additions are needed. Thanks in advance!

[read-the-docs-community]

Documentation build overview

📚 python-docs-theme-previews | 🛠️ Build #34679010 | 📁 Comparing 02664c6 against latest (a89775c)

  🔍 Preview build  

17 files changed · ± 17 modified

± Modified

• download.html
• genindex-C.html
• genindex-L.html
• genindex-T.html
• genindex-all.html
• c-api/unicode.html
• library/asyncio-task.html
• library/ctypes.html
• library/ipaddress.html
• library/json.html
• and 7 more...

[sepehr-rs]

Thanks for the review!

Sidenote: I found an issue with the sidebar while investigating this; The sidebar button's direction is reversed in RTL mode:

When closed:

When open:

I think it'd be a very small fix, but should I make a separate PR for it, or fix it here if the scope creep is acceptable?

[hugovk]

Vazirmatn is unmaintained following the death of its creator:

• https://github.com/rastikerdar/vazirmatn
• https://en.wikipedia.org/wiki/Saber_Rastikerdar

Vazirharf is a maintained fork, is that suitable?

• https://github.com/nadalaba/vazirharf

In either case, the current .woff isn't too large at 109 KB, so bundling should be fine so we don't need to use a CDN. But Vazirmatn says:

For Latin glyphs, Vazirmatn is combined with Roboto font by a build script, however there is also a version without Latin glyphs (Non-Latin).

Can we use the Non-Latin version? That'd reduce it by around half:

• Vazirmatn: I think we'd need these two:

  • 22 KB: https://github.com/nadalaba/vazirharf/blob/v34.003/misc/Non-Latin/fonts/webfonts/Vazirharf-NL%5Bwght%5D.woff2
  • 22 KB: https://github.com/rastikerdar/vazirmatn/blob/v33.003/misc/Non-Latin/fonts/webfonts/Vazirmatn-NL-Bold.woff2

• Vazirharf: just this one?

  • 50 KB https://github.com/nadalaba/vazirharf/blob/v34.003/misc/Non-Latin/fonts/webfonts/Vazirharf-NL%5Bwght%5D.woff2

[sepehr-rs]

I don't oppose using a fork, but the font and its glyph coverage are stable, and the fork doesn't offer a benefit that matters for documentation (its only difference is how Lam-Alef is handled, which is aimed at typing sites). There's also no visible difference between the two, so I'd slightly lean towards staying with the original upstream release. That said, I'm happy to switch if the project prefers a maintained font, so I'll leave the decision to you.

Good point on the Non-Latin build. Vazirmatn also has a variable-weight Non-Latin version, and it's slightly smaller than Vazirharf's:

• 46.8 KB: https://github.com/rastikerdar/vazirmatn/blob/master/misc/Non-Latin/fonts/webfonts/Vazirmatn-NL%5Bwght%5D.woff2

Please let me know what you think is best going forward, and thanks for the review!

[hugovk]

Let's stick with the original then, and go with that Non-Latin version.

We can switch to a fork later if there's a concrete need to do so. Thanks!

[hugovk]

Thanks! I added the version number in the title, so it'll go into the commit message, so we can easily check the version.

I think it'd be a very small fix, but should I make a separate PR for it, or fix it here if the scope creep is acceptable?

Let's do a new PR.

[sepehr-rs]

Thanks a lot for the review! I'll open a separate PR for that change.

[sepehr-rs]

The CI is failing with W002: Wheel contains duplicate files. Should we ignore the warning or exclude the package copy from the wheel with build.targets.wheel.exclude?

[StanFromIreland]

I think we can just ignore the warning?

[hugovk]

Let's rather exclude, so we only have one copy in the expected place? Something this:

build.targets.wheel.exclude = [ "python_docs_theme/locale/**/*.po", "python_docs_theme/static/fonts/OFL.txt" ]

Ignoring W002 means we could easily end up with other duplicates in the future without realising.

[sepehr-rs]

Makes sense. Excluded OFL.txt in pyproject.toml. One question though: doesn't this mean the license won't appear next to the font in the package? I thought the license should be bundled alongside the font.

[hugovk]

We can see the contents of the sdist at https://github.com/python/python-docs-theme/actions/runs/35627886765

It has the licence next to the font:

│   ├── [2026-09-21T16:48:06Z]  static
│   │   ├── [2026-09-21T16:47:48Z]  copybutton.js
│   │   ├── [2026-09-21T16:48:06Z]  fonts
│   │   │   ├── [2026-09-21T16:47:48Z]  OFL.txt
│   │   │   └── [2026-09-21T16:47:48Z]  Vazirmatn-NL-VF.woff2

And it also shows the wheel, with the licence in the designated licenses metadata subdir:

└── python_docs_theme-2026.9.dist-info
    ├── METADATA
    ├── RECORD
    ├── WHEEL
    ├── entry_points.txt
    └── licenses
        ├── LICENSE
        └── python_docs_theme
            └── static
                └── fonts
                    └── OFL.txt

But it doesn't need to be directly next to the font. The licence says:

2. Original or Modified Versions of the Font Software may be bundled,
   redistributed and/or sold with any software, provided that each copy
   contains the above copyright notice and this license. These can be
   included either as stand-alone text files, human-readable headers or
   in the appropriate machine-readable metadata fields within text or
   binary files as long as those fields can be easily viewed by the user.

• "... provided that each copy contains the above copyright" -> "Copyright 2015 The Vazirmatn Project Authors (https://github.com/rastikerdar/vazirmatn)"

• "and this license" -> check

• "These can be included ... in the appropriate machine-readable metadata fields within text or binary files" -> using the wheel metadata for licences in the Core Metadata Spec defined by PEP 639.