[RFC]: Migrate vLLM Docs back to Sphinx for Localization

[hwhsu1231]

Motivation.

To localize the vLLM Documentation.

Recently, I officially published my 1st localization project, cmake-docs-l10n, on GitHub:

• Preview: https://localizethedocs.github.io/cmake-docs-l10n
• Crowdin: https://localizethedocs.crowdin.com/cmake-docs-l10n
• GitHub: https://github.com/localizethedocs/cmake-docs-l10n

I can confidently say that I can manufacture similar localization projects for any Sphinx-based documentation or website.

Originally, I had planned to add vllm-docs-l10n to my to-do list, which you can see here:

https://github.com/localizethedocs/projects/issues

However, I unexpectedly discovered today that the vLLM Documentation has migrated from Sphinx to MkDocs, starting with the 0.9.0 tag.

• Commit: a1fe24d
• PR: Migrate docs from Sphinx to MkDocs #18145

This is quite regrettable because, based on my research, MkDocs currently doesn't offer the same comprehensive Internationalization with Gettext features as Sphinx.

I'm sure the vLLM team made this decision after significant discussion and evaluation. However,

if the vLLM Documentation were to migrate back to Sphinx, I would be able to add vllm-docs-l10n to my to-do list.

Proposed Change.

Migrate vLLM Docs back to Sphinx.

Feedback Period.

No response

CC List.

@hmellor

Any Other Things.

Currently, the vLLM MkDocs documentation uses the Material for MkDocs theme.

If the vLLM team decides to migrate back to Sphinx and wants to maintain a similar visual style, you might consider these Sphinx themes:

• Sphinx Material: https://bashtage.github.io/sphinx-material/
• Sphinx Immaterial: https://jbms.github.io/sphinx-immaterial/

Sincerely.

Before submitting a new issue...

• Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.

[hmellor]

Hi there,

Unfortunately we are extremely unlikely to switch back to Sphinx.

Even in the initial upgrade PR (the one you linked) we managed to remove 2600 lines of Sphinx-based boilerplate (this was almost 40% of all the lines touched in that PR!). Since then we have completely reorganised the docs to be more intuitive and begun leveraging the flexibility/hackability of MkDocs to customise the generated docs.

---

I'm sure the vLLM team made this decision after significant discussion and evaluation.

Yes, the discussion to upgrade from Sphinx to MkDocs happened on Slack.

---

The motivations for the upgrade were technical rather than theme based:

• MkDocs builds faster (very important when we have API reference of ~1000 Python files)
• MkDocs allows us to document (docs & docstrings) in pure-markdown
  • This makes the docs much more readable and browsable (you can actually browse the docs on GitHub and they are rendered pretty well!)
  • For Sphinx we used MyST parser (but this was sort of pseudo-markdown)
  • For docstrings in MyST we had to use a custom version of autodoc2 so that docstrings could be markdown
• MkDocs more modern (not necessarily an essential reason, but it was one of them)

We chose MkDocs Material simply because it was the most popular/well maintained.

---

Finally, a quick search of the MkDocs Material documentation reveals that it does support i18n internationalisation.

[hwhsu1231]

Hello, @hmellor

Finally, a quick search of the MkDocs Material documentation reveals that it does support i18n internationalisation.

Well, it does, but as I mentioned in the issue:

MkDocs currently doesn't offer the same comprehensive Internationalization with Gettext features as Sphinx.

Sphinx's i18n feature is exceptionally valuable because they can extract all translatable strings into corresponding .pot files. After preparing the translated .po files in the locale direcotry, we essentially just need to specify the following parameters on the sphinx-build command line to build the translated documentation:

-D language=<language-code> -D locale_dirs=<locale-dir>

This is something that all current MkDocs i18n-related plugins and built-in features cannot achieve. To my knowledge, the only other tool currently comparable to Sphinx's i18n feature is the mdbook-i18n-helper preprocessor, developed by Google for mdBook.

[hmellor]

Thank you for clarifying that it's the automatic extraction of translatable strings which are the key feature of Sphinx's internationalisation.

This MkDocs plugin appears to do this https://github.com/mondeja/mkdocs-mdpo-plugin? This plugin generates .po files in locale directories, just as with sphinx-build gettext:

Then a translator could translate these .po files and the translations could be added to MkDocs material as described in https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/?

[hwhsu1231]

Honestly, I previously researched the mkdocs-mdpo-plugin plugin but ultimately failed. My conclusions at the time were:

1. mdpo cannot handle all possible .md files.
2. mkdocs cannot dynamically modify configuration values in mkdocs.yml from the command line.
3. mkdocs-mdpo-plugin lacks sufficiently active and stable maintenance.

In short, it cannot "stably" handle all MkDocs-based documentation/websites in the same way Sphinx's Gettext does. Of course, I don't mean that MkDocs will be entirely unable to overcome these challenges in the future. However, it would just require a considerable amount of time and resources.

Since I've basically completed my research on the Sphinx i18n feature through cmake-docs-l10n, any Sphinx-based projects can essentially be published based on that template. If the vLLM team is willing to migrate its documentation back to Sphinx, I could manufacture vllm-docs-l10n within 1 month, theoretically. All you need to do is maintain the English source. As for the localization and its maintenance, I can help.

Therefore, I hope that the vLLM team can re-evaluate the benefits of using Sphinx to generate vLLM documentation from an "internationalization" perspective.

[SamYuan1990]

Hi,

Recently, I make an agent for i18n, and I found our document current English only. So.... I would like vote for i18n.

[hwhsu1231]

Hello vLLM Team,

Ever since the publication of my cmake-docs-l10n project, I've also published the following l10n projects:

• localizethedocs/python-docs-l10n
• localizethedocs/ros2-docs-l10n
• localizethedocs/sphinx-docs-l10n

Just as I mentioned previously:

I can confidently say that I can manufacture similar localization projects for any Sphinx-based documentation or website.

I was wondering if the vLLM team has discussed my RFC during this period and what the outcome of those discussions was.

---

For projects that have used MkDocs for a long time, I wouldn't strongly recommend migrating to Sphinx. However, for the vLLM project, it's been less than 2 months between the time vLLM officially migrated to MkDocs (marked by the v0.9.0 tag) and the initial commit of my cmake-docs-l10n project (initial commit). This makes me wonder:

What if I had completed my l10n project research a few months earlier and informed the vLLM team of my intention to create a vllm-docs-l10n project? Would there have been a chance to persuade you to stick with Sphinx?

---

The following screenshot is the vLLM zh_TW documentation generated by my testing vllm-docs-l10n project at the v0.8.5 tag for demonstration:

[hwhsu1231]

If vLLM Docs decides to migrate back to Sphinx for localization, one syntax needs a complete overhaul:

Replacing colon fences (:::) with backtick fences (```)

Otherwise, the text highlighted in the red box in the image below (and other text) will be untranslatable.

Problem Description

In the source code for vLLM Docs at the v0.8.5 tag, the docs/source/index.md file uses the following code to create its toctree:

:::{toctree}
:caption: Getting Started
:maxdepth: 1

getting_started/installation
getting_started/quickstart
getting_started/examples/examples_index
getting_started/troubleshooting
getting_started/faq
getting_started/v1_user_guide

:::

Theoretically, compared to processing a toctree directive in reST syntax, the Gettext builder should extract only the value of the :caption: field, "Getting Started". However, after trying to generate the .pot files with the Gettext builder, I found that the corresponding .pot file extracts the toctree directive in the following format:

#: ../../../source/index.md:61
msgid ":::{toctree} :caption: Getting Started :maxdepth: 1"
msgstr ""

#: ../../../source/index.md:65
msgid ""
"getting_started/installation getting_started/quickstart getting_started/"
"examples/examples_index getting_started/troubleshooting getting_started/faq "
"getting_started/v1_user_guide"
msgstr ""

#: ../../../source/index.md:72 ../../../source/index.md:112
msgid ":::"
msgstr ""

Nevertheless, I still tried translating the content of :caption: and then generating the translated document using the HTML builder:

#: ../../../source/index.md:61
msgid ":::{toctree} :caption: Getting Started :maxdepth: 1"
msgstr ":::{toctree} :caption: 開始使用 :maxdepth: 1"

The resulting document, however, did not translate "Getting Started" to "開始使用".

Alternative Solution

While the colon fence is indeed an extension supported by MyST-Parser, the Gettext builder currently has a bug in how it processes this code block. Fortunately, I've found a solution:

Replace the colon fence (:::) with a backtick fence (```)

Here's the toctree directive I modified using the "search and replace" function:

```{toctree}
:caption: Getting Started
:maxdepth: 1

getting_started/installation
getting_started/quickstart
getting_started/examples/examples_index
getting_started/troubleshooting
getting_started/faq
getting_started/v1_user_guide

```

When the Gettext builder extracts entries from this toctree directive, it will only generate the following entry:

#: ../../../source/index.md:61
msgid "Getting Started"
msgstr "開始使用"

Afterward, by using the HTML builder with the prepared .po file, the corresponding text can be successfully translated!

Note

BTW, MoonBit Docs uses backtick fences to handle MyST directives, so it doesn't run into this issue when using .po translation files.