Adding Custom Menu Items to Your Documentation Site Header (ReadtheDocs theme)

A well-organized and accessible documentation site is a cornerstone of user experience. It’s not just about presenting information but also about navigation and ease of access. Among the essential elements, the header stands out as a prime spot to include crucial links and menus for swift navigation. If you’re using the ReadTheDocs theme and seeking … Read more

Creating a Captivating Documentation Homepage with reStructuredText

A well-structured documentation homepage serves as the gateway to your product documentation. So, it must be easy to navigate and enable discoverability of your content. In this blog post, I provide a template that you can customize to create a documentation page. This template relies heavily on the elements from the sphinx-design extension, specifically cards, … Read more

Integrating Typesense with Sphinx Read the docs Template: A Step-by-Step Guide

In this guide, I will walk you through the process of integrating Typesense with the Read the docs theme for your documentation website. This integration allows you to add a powerful search feature to your documentation, making it easier for users to find the information they need. Summary: Before we begin, let’s outline the infrastructure … Read more

Customizing Changelist Description in Perforce!

Customizing Default Changelist Description in Perforce To improve the traceability of commits to perforce, we were looking to provide a changelist description template to the team. We use Perforce as a repository running on a Windows platform. Research from the internet suggested that we would have to use P4 triggers. However, our IT team had … Read more

Microsoft Word: Retain Formatting After Updating a Cross-Reference

Problem: Formatting is not retained after updating cross-reference You insert a cross-reference to a section. And, you apply a character style to display the link in blue. However, when you update the cross-reference, the character styling is lost. For example, if you have applied a style to display the link in blue, the formatting is … Read more

DITA from FrameMaker: Two Schools of Thought

Traditionally in our product group, we have been using unstructured FrameMaker as the main authoring tool for our product documentation. In late 2017, we received a requirement that customer requires our documentation source in DITA format with the PDFs too. This requirement posed a challenge. We did not have any experience working with DITA earlier, … Read more

Generate HTML from reST using Sphinx and GitHub Actions

In this post, I explain how you can write a GitHub action that will generate HTML from Restructured Text (reST) and upload the HTML files to an S3 bucket. This workflow ensures that when you merge any changes to your reST source, the HTML is automatically built and posted to your hosting provider. Introduction Creating … Read more