gamepad-coder.github.io

Welcome to the GitHub Pages Repository for my website!

I am currently using Jekyll, Sphinx, (and a lot of pre-processing and post-processing python scripts I wrote) to build my website: gamepad-coder.github.io.

How it works:

  1. For development, I build my website offline on my PC using Jekyll.
  2. When my changes are ready, I upload my files to GitHub.
  3. Then GitHub independently bakes my source files using their own installation of Jekyll, and publishes the finished product online. This service is called GitHub Pages, and you can read more about it here!

It’s awesome, free, and I’m very grateful for the service.

[~] To Do:

I plan to add a detailed walkthrough of all the tools and steps to the Documentation section of my website sometime this year.

For now, I’ll write a very brief overview here.

Folder Structure

The top level of this repository is the source directory for all the files Jekyll bakes when I type the command jekyll build. Jekyll takes any page containing front matter and processes it.

The main use of front matter is to tell Jekyll, “Hey, this page isn’t complete. This is just the content in the middle of the page. I want you to use the layout I asked for in the front matter, and put all the bells and whistles inside the finished HTML page.”

All the following are the unbaked source files, before Jekyll processes them:

The website files you actually see when you visit gamepad-coder.github.io are all located in the output directory named /_site/.

The Documentation Sub-Website

In addition to Jekyll, I am using Sphinx to create the base files in the Documentation section of the website. However, I take Sphinx’s default output files, and then modify them with additional tweaks, URL corrections, and added functionality.

The finished product is here: https://gamepad-coder.github.io/Documentation.html

The Documentation Directory

The files in /Documentation/ are the files Jekyll uses to bake the Documentation section of my website, but these are not actually the source files.

/Documentation/_Sphinx/ is the directory for all my Documentation source files.

This is also the root directory for my Sphinx project file for my Documentation: /Documentation/_Sphinx/conf.py.

(Jekyll doesn’t actually know this directory exists, and never touches it. In my Jekyll configuration file /_config.yml there is a line which says: exclude: [Documentation/_Sphinx].)

Building my Documentation, Basics

I made a custom modification of the ReadTheDocs theme for Sphinx, located under /Documentation/_Sphinx/stphinx_rtd_theme__modified/. I use this to insert a miniature version of my <header> navigation bar from my website’s Home page into the Documentation pages.

/Documentation/_Sphinx/Documentation.rst is the index file for the top of the Documentation section. Sphinx thinks of this as its own project’s root file.

This Documentation.rst contains the Table of Contents directive which references all other pages in the Documentation. This Table of Contents declared in Documentation.rst is what Sphinx uses to generate the sidebar you see on the lefthand side of my Documentation section.

If (a) your window is very narrow or (b) you’re on a mobile device, then this sidebar will show up if you click the menu button in the upper-left hand corner of the page.

When I run the command sphinx make html, Sphinx takes my custom theme and builds Documentation.rst and all the files it references (located in the subdirectories /Documentation/_Sphinx/AutoHotkey/ and /Documentation/_Sphinx/Godot/) and produces a baked set of files in a folder called /Documentation/_Sphinx/_build/.

For cleanliness of commits, I have omitted /Documentation/_Sphinx/_build from this GitHub repository. But if you install Sphinx, download this repo, navigate to /Documentation/_Sphinx/ and run sphinx make html, then /Documentation/_Sphinx/_build/ and all of its files will be generated.

Building my Documentation, Complete Steps

In order to make Sphinx’s output mesh well with the rest of my website, I manually modify URLS to be compatible with Jekyll, and to make the Sphinx files relative to their greater context as a sub-directory of the rest of the Jekyll build files.

Additionally I manually insert code-block folding in the highlighted code sections of my Documentation.

This is where my pre-processing and post-processing scripts come into play.

When I build my Documentation under /Documentation/_Sphinx/, I run the following commands in Debian’s Bash shell:

  1. sphinx_1 - custom alias
    • changes to the Sphinx project directory
    • runs ( A ) run all python pre-processing scripts.py

  2. sphinx_2 - custom alias
    • changes to the Sphinx project directory
    • runs Sphinx’s make clean html

  3. sphinx_3 - custom alias
    • changes to the Sphinx project directory
    • runs ( B ) run all python post-processing scripts.py

I sometimes will build run these alias commands in isolation to debug different things. But typically I run the final alias sphinx which runs the above three aliases.

Once these have all run, I check the local build files in /Documentation/_Sphinx/_build/.

If everything looks good, I run my final post-processing script ( C ) [AHK FINALIZE SCRIPT ] Post-process Sphinx output and place modified trunk in Jekyll's prebake Docs dir.ahk. This moves the baked files from /Documentation/_Sphinx/_build/ (which Jekyll doesn’t know about) to /Documentation/ (which Jekyll does know about and will use to build the website when I run the command jekyll build).

Briefly, what all my processing scripts in /Documentation/_Sphinx/ do.

Script-Calling Scripts:

( A ) run all python pre-processing scripts.py

( B ) run all python post-processing scripts.py

Pre-Processing Scripts:

Pre-Process 1 -- Copy AHK scripts to Sphinx source.py :

Pre-Process 2 -- Insert custom tags into AHK scripts (post-process will replace with html codeblock folding).py

Post-Processing Scripts:

Post-Process 1 -- Remove Section Headers in Documentation.html TOC.py

Post-Process 2 -- Add Codeblock Folding To Sphinx output, replace custom tags with HTML details element.py

Post-Process 3 -- Add Links to Section Captions in Sidebar TOC.py

Post-Process 4 -- Copy Videos to Output Build Directory.py

Final Post-Processing Script

This script moves files across the boundary between Sphinx and Jekyll.

(And it processes them a bit to make everything work together in Jekyll’s build process)

This was the first script I wrote here, and eventually I’ll port it to Python.

( C ) [AHK FINALIZE SCRIPT ] Post-process Sphinx output and place modified trunk in Jekyll's prebake Docs dir.ahk

Conclusion for Now

I had a ton of fun with all this, and learned so much in a short period of time.

There are a few details I’ve omitted here, but this should give you a good enough idea of what this repo is, how it’s structured, how it’s built in general, and how all the different areas mesh together.

Have a great day, and enjoy!