Posts by Matt
Translating with gettext overview
- 15 October 2021
Localization with gettext is streamlined process with responsibility distributed among original messages author, gettext tooling, and translator or translator tools. This post will help you understand extracting messages and starting new translation.
Getttext PO/POT format explained
- 15 October 2021
Gettext is internationalization (i18n) mechanism and library used not only in many software products, programming languages but also for translating Sphinx documentations. Gettext extracts strings marked “to-be-localized” from a source code (or a document) to plain text file with .po or .pot file extension. Let’s look at its format.
Debugging Sphinx extensions
- 26 April 2021
Developing extensions for Sphinx documentation projects can easily grow into a big Python project. Debugging with print() quickly becomes a no-go. Let’s have a look how to debug Sphinx extension of any size.
Best Sphinx conf.py tips
- 13 April 2021
Over the years writing documentation in Sphinx, I found I do the same tweaks in every Sphinx project’s conf.py again and again. Here are the best ones.
CSS to remove document title from Sphinx local ToC
- 07 April 2021
This week, I’m working on Documatt Sphinx Theme, a theme used for example in this blog. One of the longest postponed feature is displaying a local table of contents (ToC) in the right sidebar. By default, Sphinx displays a current document title in the local ToC, so let’s fix it.
How to modify Sphinx theme?
- 13 August 2020
Do you like your current HTML theme for Sphinx documentation project, but want only to change font family, increase the font size, change colors, and similar minor customizations? Learn common ways to customize and modify Sphinx themes.
Sphinx theming guide
- 12 August 2020
- Category: top
Tech writers should write. Delivering documentation in a visually appealing manner is almost the same important as the content itself, however. Sphinx themes are “skins” that define look & feel of documentation when outputted to HTML format. In this guide, you will learn how to customize existing or create a new theme from scratch.
Sphinx themes
- 12 August 2020
Sphinx theme is skin that changes the appearance of HTML version of the documentation. It contains HTML templates, CSS stylesheets, and static files like images, favicon, fonts, etc.
reStructuredText pitfalls
- 13 July 2020
This page title could also be What I can’t do in reStructuredText?. Unfortunately, there are areas where reStructuredText doesn’t shine, and it’s handy if you will know its limitations in advance.
reStructuredText and Sphinx guide
- 13 July 2020
- Category: top
If you starting writing in reStructuredText, you will quickly find it’s not always intuitive. In this Sphinx and reStructuredText guide, you’ll find explanation in plain English of syntax, elementary concepts and important pitfalls to avoid.
Showing code examples
- 13 July 2020
In almost any technical documentation you need to show bits of code, filenames and paths, commands and console examples. They are usually styled in monospace font with optional syntax highlighting.
Sections – structuring document
- 13 July 2020
Document structure is hierarchy of its sections. reStructuredText calls heading the section and takes different approach on section leveling than you probably expect. Section titles are decorated with the punctuation characters and importance (a section level) depends on its usage order in document.
Admonitions
- 13 July 2020
Admonitions are specially marked blocks that can appear anywhere an ordinary body element can. Readers will appreciate if you spice up your text with admonitions like tip for extra information or warning to raise their attention.
How to add a sitemap to the Sphinx project?
- 02 July 2020
Sitemap is essential part of making your website more visible for search engines. It is usually represented by the sitemap.xml file and lists URLs of all website pages, translations of pages in alternative languages, etc. sphinx-sitemap extension can easily generate sitemap for your Sphinx documentation project.
Pictures in documentation best practices
- 10 June 2020
A picture is worth a thousand words. Everybody agrees with this proverb, but taking pictures for documentation that really worth it is not always easy. I’ll share with you my personal best practices of handling images in documentation.
Editor skills of every tech writer
- 04 April 2020
Know and love your editor. Programmers and tech writers literally spend their lives in powerful text editor and IDEs but sometimes aren’t aware of all their editing features. In the following post, I share some essential skills you, as a tech writer, should definitively adopt.