/python-docs-sprint

Instructions for PyCon PL workshop

  1. Find your language in Python Developer's Guide > Documentation > Translating.
  2. If it's missing there, start a new translation.
  3. If it's not using Transifex, download Poedit.
  4. If it's using Transifex, sign up to Transifex.
  5. Request to join a language team in python-doc organization on Transifex.

Translating

  1. Select a resource you want to start translating.
  2. Locate a resource and a string in translating tool.
  3. Look for the context of the paragraph/sentence to translate in rendered (built) docs.
  4. Look for glossary terms underlined in a source string.
  5. Optionally update the glossary.
  6. Look for suggestions, and use it to base the new translation on one of them.
  7. Make sure that you fully understand the sense and context of the paragraph/sentence.
  8. Optionally you can use an external translation tool.
  9. Using above points, try to come up with a few sentences. "Would it be understandable for your friend?"
  10. You may want to consult something with the translation group, use Discord.
  11. If you're not sure, you can use Save as Suggestion.
  12. You may want to manually check the correctness of reStructuredText syntax of your translation. You can use Online Sphinx editor.

Preview nightly build (applicable to languages that uses it in their CIs)

  1. Open Actions tab in the GitHub repository.
  2. Look for most recent documentation build there.
  3. If the build fails, read through the logs and try to locate and resolve the cause.
  4. If the build succeeds, from Artifacts section download the documentation in desired version and format.

Building the documentation locally

  1. Clone CPython repository.
  2. Enter Doc directory.
  3. Call make venv.
  4. Activate the venv: .venv/bin/activate.
  5. Call make html.
  6. The generated files will be placed in the _build/html directory.

Building the translation locally

  1. Clone your language translation repository.
  2. Create directories locale/xx in cpython/Doc, where xx is your language shortcut.
  3. Create a symlink in the CPython repository pointing to freshly cloned translation. ln -s cpython/Doc/locales/xx/LC_MESSAGES python-docs-xx
  4. Call -e SPHINXOPTS="-D language='xx'" html in cpython/Doc repository.
  5. The generated files will be placed in the _build/html directory.

Fetching the translation from Transifex locally

  1. Go to Transifex user settings > API token.
  2. Generate a new token.
  3. Set it as a TX_TOKEN environment variable.
  4. In the language repository call python manage_translation.py fetch.

Further reading/tools

Presentation from PyCon2024

Google Docs