Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

autodoc translating class members to Japanese produces broken formatting #10747

Open
JulianOrteil opened this issue Aug 2, 2022 · 3 comments

Comments

@JulianOrteil
Copy link

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
Copy link
Author

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
Copy link

ninoles commented Nov 25, 2022

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
Copy link

ninoles commented Nov 25, 2022

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

3 participants