sphinx-doc / sphinx-doc/sphinx

What's up with sphinx/themes/pyramid/static/epub.css?

Open
#7,719 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

builder:epub html theme type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

It has a header that claims that it's default.css_t:

https://github.com/sphinx-doc/sphinx/blob/302c23fb5c172826499e8b3fb6d9eccd3c32d307/sphinx/themes/pyramid/static/epub.css#L1-L10

In reality, this file is very similar to basic.css_t, it has only a few differences:

https://github.com/sphinx-doc/sphinx/blob/302c23fb5c172826499e8b3fb6d9eccd3c32d307/sphinx/themes/basic/static/basic.css_t

If both files are actually needed, shouldn't they re-use the common part?

The actual file default.css_t doesn't seem to exist, yet it is mentioned in the code:

https://github.com/sphinx-doc/sphinx/blob/af62fa61e6cbd88d0798963211e73e5ba0d55e6d/sphinx/builders/changes.py#L146-L147

There is only a default.css, which is clearly different:

https://github.com/sphinx-doc/sphinx/blob/302c23fb5c172826499e8b3fb6d9eccd3c32d307/sphinx/themes/default/static/default.css

default.css is also mentioned here, which also seems out of place:

https://github.com/sphinx-doc/sphinx/blob/26f620253dbbac98f3472ac5843d2d8f1bcb2726/sphinx/builders/html/__init__.py#L464-L469

It seems to have something to do with the "changes" builder (which I've never heard of before today):

https://github.com/sphinx-doc/sphinx/blob/302c23fb5c172826499e8b3fb6d9eccd3c32d307/sphinx/themes/basic/changes/versionchanges.html#L10

I can't really check what that's all about, because the "changes" builder doesn't seem to work for me (it creates an empty output directory).

Finally, default.css is mentioned in a few places regarding configuration, where it's probably also a bit anachronistic:

https://github.com/sphinx-doc/sphinx/blob/af62fa61e6cbd88d0798963211e73e5ba0d55e6d/doc/_static/conf.py.txt#L151-L154

https://github.com/sphinx-doc/sphinx/blame/d47427e94fee59f5a76f4585dac5ed9a08383a59/doc/usage/configuration.rst#L993-L998

https://github.com/sphinx-doc/sphinx/blob/af62fa61e6cbd88d0798963211e73e5ba0d55e6d/sphinx/templates/quickstart/conf.py_t#L94-L97

What's up with all that?
Am I missing something?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing sphinx/themes/pyramid/static/epub.css_t with sphinx/themes/basic/static/basic.css_t, then trace the default.css_t and default.css references in sphinx/builders/changes.py, sphinx/builders/html/init.py, and the configuration templates. Check how the changes builder and referenced assets are exercised. Done means the stylesheet references and shared CSS are consistent, obsolete names are resolved, and the changes builder still produces its intended output.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.