sphinx-doc / sphinx-doc/sphinx

'make epub' got an unexpected filename when project name is not in English

Open
#9,502 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

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

Description

Describe the bug

in conf.py, if project value is set to a non-english name, such as a CJK(Chinese,Japan,Korean) string, this value will be ignored and the making result of epub will be sphinx.epub or ----.epub or others that can't be predicted.
(I guess that depends on whether there were any ASCII chars in the project value. All non-ASCII chars will be lost, and if there is zero ASCII char left after that ignoring operation, the filename will be sphinx.epub).

But if I add an epub_basename value in CJK, the result epub filename will be set to this value as expectation.

How to Reproduce
$ make epub
$ cd build/epub
$ ls *.epub
Expected behavior
make epub

shoud get an epub file in build/epub/
with a correct filename same to project value in conf.py

Your project

non_en_prj_demo.zip

Screenshots

No response

OS

Archlinux

Python version

3.9.6

Sphinx version

4.1.1

Sphinx extensions

No response

Extra tools

No response

Additional context

conf.py

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = '测试标题-テストタイトル-테스트 이름-Название теста'
copyright = '2021, abc'
author = 'abc'

# The full version, including alpha/beta/rc tags
release = '1'
version = '3' # to suppress the epub warning about version...

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'zh_CN'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']


#epub confs

# epub_basename = '测试标题-テストタイトル-테스트 이름-Название теста'

# if this epub_basename was set, the filename of epub will be '测试标题-テストタイトル-테스트 이름-Название теста.epub'
# if this epub_base name was not set, the file name will be `----.epub`

The Project Zip

non_en_prj_demo.zip

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 with the Sphinx EPUB build triggered by make epub, then trace how project and epub_basename from conf.py become the filename in build/epub. Reproduce the issue with the supplied non-English project and verify that the generated .epub filename preserves the configured project value when no explicit basename is set.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.