Build

This page ties together Restructured Text, Sphinx, Posts, and GitHub Pages into the end-to-end process used to write and publish this site. It covers the full workflow, from drafting pages to building the HTML and sending the result to GitHub Pages.

Write a page

Pages live under source/ as .rst files (see Restructured Text). A blog post is a normal page with an ABlog post directive near the top so it is picked up as a post rather than a plain doc:

My Post Title
=============

.. post:: 2026-07-10
    :tags: example
    :category: Website
    :author: Sam Khalilian

Post content goes here.

Note

Every page must be in a toctree or Sphinx warns that the document isn’t included in any toctree. For pages deliberately left out of every toctree, put :orphan: on the first line of the file, followed by a blank line, to suppress the warning.

Set up the environment

$ cd ~/projects/
$ git clone https://github.com/samkhalilian/blog.git docs
$ cd docs
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -r requirements.txt

On Windows (PowerShell) use py -3.11 -m venv .venv and .venv\Scripts\Activate.ps1 instead. A virtual environment only works on the OS that created it, so WSL and Windows each need their own.

Build and preview locally

Sphinx (via sphinx-build) turns the .rst sources into HTML, while ABlog additionally generates the blog archive, tag and category pages (see Sphinx and Posts):

$ sphinx-build -M html source _build
$ python3 -m http.server 8000 -d _build/html

The build also copies the separately built trade_engine docs into _build/html/projects/trade_engine (see source/conf.py), so build those first if they have changed.

If you see OSError: [Errno 98] Address already in use, another server is already using port 8000. Either stop the existing process and rerun, or choose a different port:

$ pkill -f "http.server"
$ python3 -m http.server 8001 -d _build/html

Browsers cache pages served by http.server; use Ctrl+F5 after a rebuild to see the changes.

Deploy to GitHub Pages

Once the build in _build/html looks correct, it is published to the samkhalilian.github.io repository that GitHub Pages serves from. The simplest approach is to copy the build output into a local clone of that repository, commit, and push (see GitHub Pages for setup):

Copy-Item -Path _build\html\* -Destination ..\samkhalilian.github.io -Recurse -Force
git -C ..\samkhalilian.github.io add --all
git -C ..\samkhalilian.github.io commit -m "Publish site from local build"
git -C ..\samkhalilian.github.io push origin main

Alternatively, ABlog can do the same job with a single command, using the variables described in GitHub Pages:

ablog deploy -w %WEBSITE% -p %REPODIR% -g %GITHUB_PAGES% --github-branch %GITHUB_BRANCH% --github-ssh