Build

This page ties together Restructured Text, Sphinx, ABlog and GitHub Pages into the end-to-end process used to write and publish these docs.

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: Docs
    :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 ABlog):

$ 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 pushed to the samkhalilian.github.io repository that GitHub Pages serves from (see GitHub Pages for setup and the variables used below):

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