sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.54k stars 2.12k forks source link

autodoc translating class members to Japanese produces broken formatting #10747

Open JulianOrteil opened 2 years ago

JulianOrteil commented 2 years ago

Describe the bug

In a project I'm working on, I have a requirement of translating the English documentation to Japanese. While working through the documentation, I was made aware that autodoc is not properly formatting some class members.

For example, response_cls in these images: English doc: image

Japanese translated doc: image

The documentation for response_cls is automatically generated, we have not added any docstrings in the code or the .po files, as you can see:

@dataclass
class EnableBusyReport(OSCSetCommand):
    """Enable or disable the automatic reporting of busy status changes.

    +-----------------+------+
    |Executable Timing|Always|
    +-----------------+------+
    """

    address: str = field(default="/enableBusyReport", init=False)
    response_cls: responses.Busy = field(default=responses.Busy, init=False)  # !!!!!!!!!!!!!!!!!!!!!!!!!!!!
    motorID: int
    """
    +-------+--------+
    |STEP400|1-4, 255|
    +-------+--------+
    |STEP800|1-8, 255|
    +-------+--------+
    """
    enable: bool
    """If True, enable the reporting.

    +-------+-----+
    |Default|False|
    +-------+-----+
    """
    callback: Optional[Callable[..., None]] = None

How to Reproduce

We use ReadTheDocs to automatically build our documentation. The issue can be seen here for the Japanese: https://python-step-series.readthedocs.io/ja/latest/python-step-series/api/stepseries.html#stepseries.commands.EnableBusyReport

I'm not sure how to view the translated docs locally, but here are the commands to build the English versions at least.

git clone https://github.com/ponoor/python-step-series.git
cd python-step-series
git checkout documentation
pip install -r requirements.txt
pip install -e .
tox -e docs

Expected behavior

The Japanese formatted class members to match their English counterparts.

Your project

https://github.com/ponoor/python-step-series.git

Screenshots

No response

OS

Ubuntu 20.04

Python version

3.9

Sphinx version

latest

Sphinx extensions

"sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.todo", "sphinx.ext.autosummary", "sphinx.ext.viewcode", "sphinx.ext.coverage", "sphinx.ext.doctest", "sphinx.ext.ifconfig", "sphinx.ext.mathjax", "sphinx.ext.napoleon"

Extra tools

Chrome or Edge, ReadTheDocs

Additional context

No response

JulianOrteil commented 2 years ago

For clarification, we believe the exact issue to be a lack of a space between :py:class:`~stepseries.responses.Busy` and の別名です。 in the example image above.

ninoles commented 1 year ago

I have the same problem, and it's just a space missing in the translation of alias of %s, which is translated by %sの別名です. Instead, the translation should add a space (as it does elsewhere) to be %s の別名です.

ninoles commented 1 year ago

Short workaround for those who cannot wait: Copy https://github.com/sphinx-doc/sphinx/blob/v5.3.0/sphinx/locale/ja/LC_MESSAGES/sphinx.po into your locale folder, with the sphing name, and replace %sの別名です with %s の別名です. The sphinx.mo in your locale folder will override the one in sphinx.