search

sphinx-doc / sphinx

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

Make synopsis translatable #9935

Open eviau opened 2 years ago

eviau commented 2 years ago

Thank you for building and maintaining Sphinx, it is a great project !

Is your feature request related to a problem? Please describe.

I have been part of the python-docs-fr localization project.

I wanted to translate the pymodule index page: https://docs.python.org/fr/3/py-modindex.html

As far as I understand, this page is generated automatically by Sphinx. The synopsis are not available in any .po file.

How to make them available for translation?

I believe that having this page accessible in the same locales as the docs is pivotal in navigating the docs in the chosen locale.

Describe the solution you'd like

I would like to have access to the synopsis on this page, either in one associated po file, or in the respective modules po files.

Describe alternatives you've considered

I did try to discover how to make the changes by myself, but my understanding of the Sphinx project does not enable me to make the changes, in either a PR to the main branch of the project, or as a sphinx extension, or a sphinxcontrib package.

As far as my understanding goes, the changes needs to be made in Sphinx itself, not in sphinx-intl nor docutils.

Additional context

This question was part of https://github.com/python/python-docs-fr/issues/1705

I would be happy to work towards a solution for this feature with someone else in a pair programming setting, or to have some sort of support/mentoring to do so.

eviau commented 2 years ago

My current main insight that might work would be to implement the translatable class:

https://github.com/sphinx-doc/sphinx/blob/56f97d71a2b1733ebf401d357a634e2d7e4c896e/sphinx/addnodes.py#L47

in the index class:

https://github.com/sphinx-doc/sphinx/blob/56f97d71a2b1733ebf401d357a634e2d7e4c896e/sphinx/addnodes.py#L378

Does that make any sense ?

eviau commented 2 years ago

I have also looked at https://github.com/sphinx-doc/sphinx/pull/7979 and https://github.com/sphinx-doc/sphinx/pull/2880 for getting a better understanding of how to do this.

eviau commented 5 months ago

It's been a while - wanted to note that there are some good hints in https://github.com/sphinx-doc/sphinx/issues/11956#issuecomment-1931559185

I believe that the synopsis is already a node, but I might be wrong...

Would it be possible to add a help wanted label to this issue ?

eviau commented 4 months ago

I continued researching this issue.

I think this could be used: https://www.sphinx-doc.org/en/master/extdev/i18n.html

My question is: is this only meant for extensions, or is this meant to be used in general?

Would someone know?