Build
=====

This page ties together :doc:`rst`, :doc:`sphinx`, :doc:`ablog` and :doc:`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 :doc:`rst`). 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:

.. code-block:: rst

    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
----------------------

.. code-block:: bash

    $ 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 :doc:`sphinx` and :doc:`ablog`):

.. code-block:: bash

    $ 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:

.. code-block:: bash

    $ 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 :doc:`github_pages` for setup and the variables used below):

.. code-block:: bat

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