I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.
Sphinx – Python Documentation Generator
Supports many output formats.
Internationalization (i18n): Translate into other languages without changing the code. GNU gettext is used frequently.
Tip: Install sphinx-intl to make it easier to setup.
Better to setup more automation. He found himself writing tools to show the workflow, rather than typing commands.
Transifex — Online translation service, and you can use “pip” to install transifex-client.
Tips for translating Sphinx documentation
- Use English for all text inside code. The source code isn’t part of the translation.
- Always use inline syntax, otherwise the URL will get lost when using aliases.
- Maintain versioned URLs. Use extlinks extension to define URLs in the configuration.
- Special cases — ifconfig
- Link checking — linkcheck
- Build all languages at once.
- Method to add a “landing page”.
- Setting for translations.
- Use gettext_compact to create a single catalog.
- Language switch template.
- Merge sphinx-into into Sphinx.
- Move Transifex support from spinxh-intl to a new extension.
- Allow to build all languages with a single command.