About The Website

Our quest for the perfect method to create a website for sharing course materials has been quite the journey. Despite numerous trials with various content publishing platforms, it was Sphinx that ultimately emerged as the most satisfying solution.

LMS to External Website

The journey began within the confines of the university’s traditional Learning Management System (LMS). Back when I worked with LMSs like Desire2Learn, it offered some enticing functionalities. I had even crafted some impressive themes, and the system’s integration with CSS was straightforward. However, when the entire Florida State System of Universities transitioned to Canvas, I had to bid farewell to a few of my cherished capabilities. Most notably, the support for CSS within embedded HTML was lost, even though I gained access to other valuable features. Furthermore, Canvas’ approach to synchronizing content across multiple course shells proved to be quite intricate.

Google Drive Integration

As a programmer who staunchly adheres to the “Do not repeat yourself” principle, I am disheartened by the constant need to copy, paste, import, and export materials on Canvas. I’ve diligently searched for efficient ways to host shared content so that I can make changes once and have those updates reflect everywhere. Given Canvas’s robust support for embedding Google Docs or files hosted on Google Drive, I initially considered Google Drive as an excellent alternative. However, a significant drawback in this scenario is that Google Docs doesn’t align with my preferred document handling style.

I, like many other programmers, favor pure text formats because they can be managed using version control systems just like source code files. In comparison, editing documents in Google Docs feels markedly unpleasant when compared to a proficient integrated development environment (IDE) or programmer’s text editor.

Latex to PDFs

Creating pure text formatted documents offers a range of possibilities, with LaTeX being the most evident choice. While I lean towards LaTeX when dealing with PDF publications, there isn’t a straightforward method for seamlessly generating and publishing these documents online. The process of converting to PDF and hosting on Google Drive becomes a significant hassle each time I need to update the content.

Markup Languages and Site Generating Platforms

Markdown’s limitations in extensibility and the intricate formatting requirements of my documents, which encompass source codes and cross-references, render it an unsuitable choice. It became evident that the reStructuredText (RST) format, with its rich feature set and extensibility, offers the best solution. Before discovering Sphinx, I had experimented with the RST-based static website generator Pelican and found it generally satisfactory. While I’ve been using Sphinx for documentation purposes for a while, I finally uncovered its capability to create websites as well.

Finally Sphinx+ReStructuredText

Now I have this website with contents written as RST documents, compiled with Sphinx and hosted on GitHub pages. Very happy with this combination.