Techwriter at work blog.

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


All Posts

How to modify Sphinx theme?

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.

Read more ...


Sphinx theming guide

  • 12 August 2020
  • Author: Matt
  • 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.

Read more ...


Sphinx themes

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.

Read more ...


Sphinx errors

  • 26 July 2020
  • Category: top

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

Read more ...


reStructuredText and Sphinx syntax

  • 13 July 2020
  • Author: Matt
  • Category: top

If you starting writing in reStructuredText, you will quickly find it’s not always intuitive. In this Sphinx and reStructuredText syntax guide, you’ll find explanation in plain English of elementary concepts and important pitfalls to avoid.

Read more ...


Showing code examples

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.

Read more ...


Sections – structuring document

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.

Read more ...


Admonitions

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.

Read more ...


How to add a sitemap to the Sphinx project?

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.

Read more ...


Pictures in documentation best practices

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.

Read more ...


Editor skills of every tech writer

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.

Read more ...