TechWriter at work blog logo

TechWriter at work blog

Living and writing documentation at Documatt, small team of programmers that write documentation too.

Hottest posts#

  • Sphinx Errors on Sep 04, 2023 🏷️ sphinx

    List of common Sphinx, Docutils and reStructuredText warnings and errors. Each issue is well explained, illustrated by an example, and offers solution.

  • Sphinx Themes on Aug 12, 2020 🏷️ sphinx

    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.

  • Pictures in documentation best practices on Jun 10, 2020 🏷️ docs, tips

    Generally, pictures in documentation serve two purposes – they are a complement to the text or replace the textual description. Some people learn better with words, others with pictures (or videos).

Recent Posts#

  • Sphinx Errors on Sep 04, 2023 🏷️ sphinx

    List of common Sphinx, Docutils and reStructuredText warnings and errors. Each issue is well explained, illustrated by an example, and offers solution.

  • Creating URL-encoded URLs in Falcon web framework on Aug 02, 2023 🏷️ falcon-web-framework, python

    REST APIs can pass another URL as part of the API’s URL. E.g., /cache/foo%2Fbar.html is passing foo/bar.html to /cache/ endpoint. Building these APIs in Python is difficult because of the unfortunate omission of the WSGI specification that doesn’t provide the means to access the raw request URL. WSGI offers web frameworks only already URL-decoded PATH_INFO CGI variable. I.e., for the previous example, they actually got /cache/foo/bar.html which likely leads to 404 Not Found as there is no cache/foo/bar.html endpoint.

  • Centralized user messages in Python apps on Jul 16, 2023 🏷️ falcon-web-framework, python

    Helpful errors with error codes. Do you love it too? During the development of the Snippets, an online preview tool for reStructuredText (and Markdown coming soon), I tried to produce actually helpful messages to the API user. I started with collecting text strings that could appear to users across the codebase and put them into a single file.

  • URL encoding on Jun 15, 2023 🏷️ python

    URL encoding (also known as percentage encoding) is a way to pass around characters otherwise prohibited in the URL and HTML forms because they have special meanings. For example, to use http:// as part of a URL, not its beginning, it has to be %-encoded to http%3A%2F%2F.

  • Translating with gettext overview on Oct 15, 2021 🏷️ i18n

    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 on Oct 15, 2021 🏷️ i18n

    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 on May 26, 2021 🏷️ sphinx

    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 on May 13, 2021 🏷️ sphinx

    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 on May 07, 2021 🏷️ sphinx

    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? on Aug 13, 2020 🏷️ sphinx

    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 post, you will learn how to customize existing or create a new theme from scratch.

  • Sphinx Themes on Aug 12, 2020 🏷️ sphinx

    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.

  • How to add a sitemap to the Sphinx project? on Jul 02, 2020 🏷️ sphinx

    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 on Jun 10, 2020 🏷️ docs, tips

    Generally, pictures in documentation serve two purposes – they are a complement to the text or replace the textual description. Some people learn better with words, others with pictures (or videos).

  • Editor skills of every tech writer on May 04, 2020 🏷️ productivity

    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.