Documentation build overview

📚 python-docs-theme-previews | 🛠️ Build #34711042 | 📁 Comparing 8fea77a against latest (a89775c)

  🔍 Preview build  

± Modified

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

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?

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

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!

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!

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

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?

I think we can just ignore the warning?

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.

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.

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.

Thanks a lot for taking the time to explain this to me! I understand it now =).

Hey @StanFromIreland, just checking in on this. I think it's ready to merge, and I’d love to see Vazirmatn support added to the Farsi documentation!

Thanks a lot for the thorough review from both of you @StanFromIreland @hugovk! I really appreciate it =).

@sepehr-rs And thanks for all your work on this!