Repository navigation
docs: fix broken headings and wrong FFmpeg instructions in installation page - #2509
Merged
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 at3b1b.github.io/manim/getting_started/installation.html:
Three separate problems follow from that section:
#leaks into the rendered heading text, and one heading spells theprogram
FFmepeg.Install FFmpeg,so they are siblings rather than children and the parent section renders with
no body at all.
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
.7zarchive 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 Pygmentslexer, so the block loses highlighting.
Proposed changes
Install FFmpegwith the^underline this docs tree already uses for thatlevel, and fix the
FFmepegspelling.Install FFmpega body, moving theffmpeg -versioncheck there so itapplies to all three platforms instead of only Linux.
brew install ffmpeg, matching the Homebrew instructions already in theREADME.
cmdlexer tobat.$prompts from the Linux block.sphinx_copybuttonis enabled andcopybutton_prompt_textis not configured, so the copy button currentlyyields
$ sudo apt update, which fails when pasted.System requirements are:and the doubledslash in
https://www.opengl.org//.the block below it, which clones the repository before creating the
environment.
No installation command changes behaviour apart from the macOS one, which was
pointing at the wrong platform.
Test
Code:
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_includedwarnings underdocumentation/, two "Title underline tooshort" warnings in
custom_config.rst, onetoc.not_readablefor a missinggetting_started/config, and one search-index notice that only appears becausethe command above builds a single page rather than the whole tree.
Before:
After:
The rendered heading tree changes from eight flat sections to a nested one:
# Install FFmepeg Linux# Install FFmpeg MacOSBuilt 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.