TechWriter at work blog logo

TechWriter at work blog

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


Posted in 2023

Sphinx Errors

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

Read more ...


Creating URL-encoded URLs in Falcon web framework

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.

Read more ...


Centralized user messages in Python apps

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.

Read more ...


URL encoding

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.

Read more ...