Latest articles#
Different template for a document in Sphinx on Mar 06, 2025 in sphinx-theming
The infrequently used Sphinx conf.py
html_additional_pagesoption is very valuable if you need to customize some pages in your Sphinx documentation website, while most are identical.
What is Sphinx built-in search, and how to use it in themes? on Jan 10, 2025 in sphinx-theming
Sphinx is a powerful documentation generator with features that enhance content usability. Its built-in search offers a simple way to find information within your documentation. This guide will help you implement and customize Sphinx’s search in your themes for a better user experience for documentation readers.
How to insert video to Sphinx document on Nov 21, 2024 in sphinx, howto
Although it sounds easy, it’s not straightforward. Sadly, pure Sphinx and the underlying library Docutils do not directly support inserting videos into documents. But we will show you two approaches to insert it anyway.
Popular articles#
How to insert video to Sphinx document on Nov 21, 2024 in sphinx, howto
Although it sounds easy, it’s not straightforward. Sadly, pure Sphinx and the underlying library Docutils do not directly support inserting videos into documents. But we will show you two approaches to insert it anyway.
Creating URL-encoded URLs in Falcon web framework on Aug 02, 2023 in python, falcon-framework
REST APIs can pass another URL as part of the API’s URL. E.g.,
/cache/foo%2Fbar.htmlis passingfoo/bar.htmlto/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.
Sphinx Themes: Introduction on Aug 12, 2020 in sphinx-theming
Sphinx theme is a collection of files 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 in writing-docs
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).
All articles#
Different template for a document in Sphinx on Mar 06, 2025 in sphinx-theming
The infrequently used Sphinx conf.py
html_additional_pagesoption is very valuable if you need to customize some pages in your Sphinx documentation website, while most are identical.
What is Sphinx built-in search, and how to use it in themes? on Jan 10, 2025 in sphinx-theming
Sphinx is a powerful documentation generator with features that enhance content usability. Its built-in search offers a simple way to find information within your documentation. This guide will help you implement and customize Sphinx’s search in your themes for a better user experience for documentation readers.
How to insert video to Sphinx document on Nov 21, 2024 in sphinx, howto
Although it sounds easy, it’s not straightforward. Sadly, pure Sphinx and the underlying library Docutils do not directly support inserting videos into documents. But we will show you two approaches to insert it anyway.
3 Steps for Release Notes Which Users Will Love on Oct 18, 2024 in writing-docs
Release notes (RNs) are a specific type of documentation for software applications. No matter if you call it changelogs, announcements, or ‘what’s new’. Unfortunately, they’re often poorly maintained or missing altogether because people tend to skip over them.
Sphinx Versions Summary on Jun 26, 2024 in sphinx
On this page, we’ll summarize a few recent Sphinx releases. We don’t want to duplicate the official Sphinx changelogs, but briefly highlight the most important changes and list supported Python and Docutils versions.
Documatt 1.0 released. Finale or startline? on Jun 26, 2024 in company
🎉 Documatt is finally here 🎉. For everyone, not just our friends and fellow tech writers. After 12+ months of development and 6 months of closed beta, you can now author in Markdown/reStructuredText and host your next documentation with us.
Creating URL-encoded URLs in Falcon web framework on Aug 02, 2023 in python, falcon-framework
REST APIs can pass another URL as part of the API’s URL. E.g.,
/cache/foo%2Fbar.htmlis passingfoo/bar.htmlto/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.
Centralized user messages in Python apps on Jul 16, 2023 in python, falcon-framework
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 in 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 tohttp%3A%2F%2F.
Translating with gettext overview on Oct 15, 2021 in 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 in 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
.poor.potfile extension. Let’s look at its format.
Debugging Sphinx extensions on May 26, 2021 in 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 in sphinx
Over the years writing documentation in Sphinx, I found I do the same tweaks in every Sphinx project’s
conf.pyagain and again. Here are the best ones.
How to modify Sphinx theme? on Aug 13, 2020 in sphinx, sphinx-theming, howto
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: Introduction on Aug 12, 2020 in sphinx-theming
Sphinx theme is a collection of files 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 in sphinx, howto
Sitemap is essential part of making your website more visible for search engines. It is usually represented by the
sitemap.xmlfile 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 in writing-docs
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 (JetBrains IDEs) on May 04, 2020 in 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.
