Assignment 2 Report: Static Personal Blog Website

Introduction

This report documents the process of setting up, managing, and deploying a static personal blog website for Assignment 2.

Tool Selection

I chose Sphinx to generate the static site. Sphinx is a robust, well-established documentation generator written in Python. It natively supports reStructuredText, but with the recommonmark extension, it provides excellent Markdown support. I chose Sphinx because it is straightforward to set up, highly customizable, and perfectly suited for creating clean, static web pages for text-heavy content like reports and blogs.

Setup Process

  1. Environment Preparation: Installed the required packages using pip install sphinx sphinx-markdown-parser recommonmark.

  2. Initialization: Created a blog directory and initialized a Sphinx project using sphinx-quickstart, separating the source and build directories.

  3. Configuration: Modified conf.py to enable Markdown support by adding recommonmark to the extensions list and setting the source_suffix to accept .md files.

  4. Content Creation: Added Markdown files including about.md, assignment1_report.md (integrating the previous assignment), and this report (assignment2_report.md). Updated the index.rst toctree to link them all together.

  5. Building: Ran make html to generate the static HTML files into the _build/html directory.

Git Management Process

The project uses Git for version control to track logical steps in development.

  • Commit 1: Initial setup of Sphinx project

    • Reason: To establish the repository and save the initial file structure generated by sphinx-quickstart, along with a .gitignore to prevent tracking build artifacts.

  • Commit 2: Added Markdown support and configuration

    • Reason: To save the configuration changes in conf.py that enable the parsing of .md files, a crucial requirement for the project.

  • Commit 3: Added Assignment 1 integration and homepage

    • Reason: To commit the integration of the previous assignment’s report and the initial home/about pages.

  • Commit 4: Added Assignment 2 documentation

    • Reason: To save the project report documenting the process and tool choices.

  • Commit 5: Finalized structure and built HTML

    • Reason: To mark the project as complete and ready for deployment.

Deployment

The generated static HTML files (located in the _build/html directory) can be served locally using a simple HTTP server (e.g., python -m http.server) or hosted on platforms like GitHub Pages.