Skip to content

docs: correct custom_config keys and drop a dangling toctree entry - #2512

Open
ting-hong-shieh wants to merge 1 commit into
3b1b:masterfrom
ting-hong-shieh:docs-custom-config-sync
Open

ting-hong-shieh wants to merge 1 commit into
3b1b:masterfrom
ting-hong-shieh:docs-custom-config-sync

Conversation

@ting-hong-shieh

Copy link
Copy Markdown
Contributor

Motivation

Partially addresses #2378, which reports that the custom configuration page has drifted from the actual config format.

Two of the options it documents do not exist in manimlib/default_config.yml. Because an unrecognised key in custom_config.yml is simply ignored, someone following the page gets no error — the setting just never takes effect:

  • The page calls it loglevel. The real key is log_level (manimlib/default_config.yml), read in manimlib/config.py as config["log_level"].
  • Under text, the page calls it text_alignment and describes it as "Default text alignment for LaTeX". The real key is alignment, and it is read in MarkupText.__init__ as text_config.alignment, so it sets the default for Text, not for LaTeX. text_alignment does not appear anywhere in manimlib/.

Two smaller things showed up while building the docs:

  • The scene and text title underlines are shorter than their titles, which Sphinx warns about.
  • docs/source/index.rst still lists getting_started/config in the Getting Started toctree. That file was deleted in 44b7d33 (Dec 2022), so Sphinx warns on every build.

Proposed changes

  • docs/source/documentation/custom_config.rst
    • loglevel → log_level
    • text_alignment → alignment, with a description that matches what the key actually does
    • lengthen the scene and text title underlines
    • fix four typos in the surrounding prose (Valuess, manimm, pallete, withinn) and one ungrammatical sentence under universal_import_line
  • docs/source/index.rst
    • drop the getting_started/config toctree entry

Deliberately not in this PR, to keep it easy to review:

  • The directories section is also out of date, in a way that needs more than a rename: output, raster_images, vector_images and sounds are nested under directories.subdirs in the yml rather than directly under directories, and the two directory-tree examples still show separate images/ and videos/ folders. I would rather verify that against a real render and send it separately.
  • The five sections with no documentation at all (vmobject, mobject, embed, resolution_options, key_bindings).
  • The website ↔ GitHub cross-linking also asked for in Clarification Needed on Custom Configuration Documentation #2378, which is a repository setting rather than a docs change.

Test

Code: the same build CI runs, on master (5d107b1) and on this branch, with Python 3.12 and docs/requirements.txt (Sphinx 9.1.0):

pip install -r docs/requirements.txt
cd docs && make html

Result: build succeeded both times; warnings go from 9 to 6.

The three that disappear are exactly the ones this PR targets:

docs/source/documentation/custom_config.rst:123: WARNING: Title underline too short.
docs/source/documentation/custom_config.rst:128: WARNING: Title underline too short.
docs/source/index.rst:11: WARNING: toctree contains reference to nonexisting document 'getting_started/config' [toc.not_readable]

The remaining 6 are pre-existing toc.not_included warnings for the autodoc index pages under documentation/, untouched here.

Diffing the rendered custom_config.html between the two builds shows only the intended edits — the section structure is otherwise byte-identical, so the shorter underlines were not changing how the page rendered, only warning.

One consequence worth flagging: the heading anchor changes from #loglevel to #log-level. Nothing in this repository links to the old anchor, but an external deep link would break.

The custom configuration page named two options that do not exist in
manimlib/default_config.yml, so following it produced settings manim
silently ignores:

- `loglevel` is spelled `log_level` (default_config.yml, read by
  manimlib/config.py in `log.setLevel`)
- `text_alignment` is spelled `alignment`, and it sets the default
  alignment of `Text`, not of LaTeX (read as `text_config.alignment` in
  manimlib/mobject/svg/text_mobject.py)

The `scene` and `text` title underlines were shorter than their titles,
and docs/source/index.rst still listed `getting_started/config`, deleted
in 44b7d33 back in 2022. Both raised Sphinx warnings.

Also fixes four typos in surrounding prose.
@ting-hong-shieh
ting-hong-shieh marked this pull request as ready for review August 19, 2026 16:25

This branch has not been deployed

No deployments
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.

1 participant