# Blogging with Sphinx¶

## What is Sphinx?¶

Sphinx is a document generator tool which was originally written for generating Python documentation. Sphinx uses reStructuredText as its markup language but you can write in markdown too.

## Blogging using Sphinx¶

I have created this blog using Sphinx and its related technologies with inspiration from Predictably Noisy. While there are many static site generators available such as Hugo, Jekyll and others I am familiar with Python’s ecosystem the most which led to my decision of using Sphinx. The bonus is that using myst_nb or nbsphinx Jupyter notebooks can be directly rendered into articles or pages for the website. As per my knowledge none of the other popular static site generators provide ability to render Jupyter notebooks directly into blog posts. In addition to that Sphinx gives you a rich markup to write your articles.

Tools used in this blog.

• Sphinx - Docs

• Ablog - Docs

• MyST{NB} - Docs

• Pydata theme - Docs

• Github Pages - Hosting Platform

Using the above tools the user has the ability to write in the markdown syntax or the restructured text syntax. You can use myst_nb or nbsphinx to parse the markdown syntax in both markdown files and Jupyter notebooks.

There are many different themes available for Sphinx but I am using the Pydata theme. It should be fairly easy for someone to set up a similar structure who is familiar with the aforementioned tools.

## The power of ReStructured Text¶

ReStructured text gives you the power to write and express complex markups easily which includes the below listed directives.

• code blocks

• tables

• footnotes

• references

• and more …

A brief demonstration of the rich markup capability. For more details you can refer to this link for writing in markdown files and this link for writing in ReStructured text files. I am bit biased towards writing in markdown as I have been doing so for years thus I have chosen the MySt parser but both are equally good choices. ReStructured is widely used in the Python community.

Code Block

Code blocks for various languages are supported. You can put in line numbers and emphasise selected lines as well. You can also include code from source files if needed.

Python Code

 1 2 3 4 5 6 # Python demo.py class X: def __init__(self,foo): self.foo = foo 

C Code

 10 11 12 13 14 15 16 17 18 19 20 21 22 23 // C demo.c #include int addition(int num1, int num2) { int sum; /* Arguments are used here*/ sum = num1+num2; /* Function return type is integer so we are returning * an integer value, the sum of the passed numbers. */ return sum; } 

Note

Warning

Equations

Support for math and equations.

(1)$e^{i\pi} + 1 = 0$

Tables

Support for tables.

Token

Description

Example

FrontMatter

A YAML block at the start of the document enclosed by ---

---
key: value
---


Footnotes

A longer footnote definition.1

This is not part of the footnote.

1

This is the footnote definition.

That continues for all indented lines

• even other block elements

Plus any preceding unindented lines, that are not separated by a blank line