Skip to content

docs: fix broken headings and wrong FFmpeg instructions in installation page - #2509

Merged
3b1b merged 1 commit into
3b1b:masterfrom
ting-hong-shieh:fix-installation-docs
Aug 17, 2026
Merged

3b1b merged 1 commit into
3b1b:masterfrom
ting-hong-shieh:fix-installation-docs

Conversation

@ting-hong-shieh

Copy link
Copy Markdown
Contributor

Motivation

The FFmpeg part of the installation page has been broken on the published docs
since 71ab276 (May 2023). It was written with Markdown heading syntax inside an
RST file, so the # characters render literally at
3b1b.github.io/manim/getting_started/installation.html:

Install FFmpeg
Install FFmpeg Windows
# Install FFmepeg Linux
# Install FFmpeg MacOS

Three separate problems follow from that section:

  • The # leaks into the rendered heading text, and one heading spells the
    program FFmepeg.
  • All three platform headings use the same underline level as Install FFmpeg,
    so they are siblings rather than children and the parent section renders with
    no body at all.
  • The macOS step tells the reader to download
    https://www.gyan.dev/ffmpeg/builds/ffmpeg-git-full.7z. That site states
    "Builds require Windows 10 or later", so this hands macOS users a Windows
    binary, and it calls the .7z archive a ZIP file.

The section also emits two Sphinx warnings: the macOS link uses single
backticks, which docutils reads as an unterminated interpreted-text start-string,
and the Windows block declares .. code-block:: cmd, which is not a Pygments
lexer, so the block loses highlighting.

Proposed changes

  • Rewrite the FFmpeg headings as proper RST, nested one level under
    Install FFmpeg with the ^ underline this docs tree already uses for that
    level, and fix the FFmepeg spelling.
  • Give Install FFmpeg a body, moving the ffmpeg -version check there so it
    applies to all three platforms instead of only Linux.
  • Replace the Windows-only gyan.dev download in the macOS step with
    brew install ffmpeg, matching the Homebrew instructions already in the
    README.
  • Change the cmd lexer to bat.
  • Drop the $ prompts from the Linux block. sphinx_copybutton is enabled and
    copybutton_prompt_text is not configured, so the copy button currently
    yields $ sudo apt update, which fails when pasted.
  • Fix a full-width colon (U+FF1A) in System requirements are: and the doubled
    slash in https://www.opengl.org//.
  • Reword the Anaconda lead-in from "Create a conda environment using" to match
    the block below it, which clones the repository before creating the
    environment.
  • Strip trailing whitespace from the lines this change already touches.

No installation command changes behaviour apart from the macOS one, which was
pointing at the wrong platform.

Test

Code:

pip install -r docs/requirements.txt
cd docs/
sphinx-build -E -b html source /tmp/out source/getting_started/installation.rst

Result:

Both warnings from this file are gone, taking the build from 12 warnings to 10.
The remaining 10 all come from other files and are untouched by this change:
six toc.not_included warnings under documentation/, two "Title underline too
short" warnings in custom_config.rst, one toc.not_readable for a missing
getting_started/config, and one search-index notice that only appears because
the command above builds a single page rather than the whole tree.

Before:

installation.rst:36: WARNING: Inline interpreted text or phrase reference start-string without end-string. [docutils]
installation.rst:21: WARNING: Pygments lexer name 'cmd' is not known [misc.highlighting_failure]
build succeeded, 12 warnings.

After:

build succeeded, 10 warnings.

The rendered heading tree changes from eight flat sections to a nested one:

Before After
h1 Installation h1 Installation
h2 Install FFmpeg h2 Install FFmpeg
h2 Install FFmpeg Windows   h3 Windows
h2 # Install FFmepeg Linux   h3 Linux
h2 # Install FFmpeg MacOS   h3 macOS
h2 Directly h2 Directly
h2 Directly (Windows) h2 Directly (Windows)
h2 For Anaconda h2 For Anaconda

Built with Sphinx 9.1.0 and furo, per docs/requirements.txt.

One thing I left alone on purpose: this page recommends TeXLive-full for
Windows while the README recommends MiKTeX. That is a recommendation to make
rather than a rendering defect, so it seemed out of scope here. Happy to follow
up if you want them aligned.

…on page

The FFmpeg section was added with Markdown heading syntax, so two headings
render a literal '#' on the published docs site, one of them misspelled as
'FFmepeg'. All three platform sections sat at the same level as their parent,
leaving 'Install FFmpeg' with an empty body.

The macOS step pointed at a gyan.dev build, which is Windows-only, and called
the .7z archive a ZIP file. Its single-backtick link syntax also emitted a
docutils warning. Replace it with the Homebrew command already used in the
README.

Also drop the shell prompts from the Linux block so the copy button yields
runnable commands, correct the unknown 'cmd' Pygments lexer to 'bat', fix a
full-width colon and a doubled URL slash, and align the Anaconda lead-in with
the commands it introduces.
@3b1b
3b1b merged commit b164d6b into 3b1b:master Aug 17, 2026
1 check passed
@ting-hong-shieh
ting-hong-shieh deleted the fix-installation-docs branch October 23, 2026 19:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants