Skip to content

Commit f3d3c67

Browse files
xames3xames3
authored
Migrate to reStructuredText from Feature → Development (#2)
* build(branching scheme): add new publishing configs * chore(urls): remove unicode replacement for dash * feat(getting started): add new guides as introduction * fix(typo): resolve branch name --------- Signed-off-by: Akshay Mestry <xa@mes3.dev>
1 parent bd8d71d commit f3d3c67

File tree

7 files changed

+603
-25
lines changed

7 files changed

+603
-25
lines changed

‎.github/workflows/publish-dev-pages.yaml

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# TOPST SCHOOL's GitHub Pages Dev Branch Publishing Workflow
2+
# ==========================================================
3+
#
4+
# Author: Akshay Mestry <xa@mes3.dev>
5+
# Created on: Sunday, September 01 2024
6+
# Last updated on: Sunday, September 01 2024
7+
8+
# Workflow name displayed in TOPST SCHOOL's "Actions" tab.
9+
name: DEV | Build and Deploy Documents
10+
11+
# A workflow with the following "on" value will run when a "push" is made
12+
# to the "dev" branch in the workflow's repository. For example, the "push"
13+
# event has a branches filter that causes this workflow to run only when
14+
# a push to a branch that matches the branches filter occurs, in this
15+
# case, the "dev" branch.
16+
on:
17+
push:
18+
branches:
19+
- dev
20+
21+
# We're using permissions to modify the default permissions granted to
22+
# the ``GITHUB_TOKEN``, adding or removing access as required, so that we
23+
# only allow the minimum required access.
24+
permissions:
25+
contents: write # Only write permissions to the repository contents are needed for deployment.
26+
27+
# A map of variables that are available to the steps of all jobs in the workflow.
28+
env:
29+
OUTPUT_DIR: docs/build/ # Directory where Sphinx will output the built HTML files.
30+
SOURCE_DIR: docs/source/ # Directory containing the Sphinx source files (rST or MD).
31+
PUBLISH_BRANCH: gh-pages # Branch where the static site will be published.
32+
PY_BUILD: 3.12.1 # Python version to be used for building the documentation.
33+
34+
# We're using concurrency to ensure that only a single job or workflow
35+
# using the same concurrency group will run at a time.
36+
concurrency:
37+
group: ${{ github.ref }} # Groups by branch, so jobs in the same branch won't overlap.
38+
cancel-in-progress: true # Cancels any currently running jobs in the same group if a new one starts.
39+
40+
# A workflow run is made up of one or more jobs, which run in parallel by default.
41+
# The ``ubuntu-latest`` label currently uses the Ubuntu 22.04 runner image.
42+
jobs:
43+
build:
44+
runs-on: ubuntu-latest # Runs the job on the latest available Ubuntu runner.
45+
steps:
46+
# Step 1: Check out the code from the repository to the runner.
47+
- name: Checkout TOPST SCHOOL Code (Dev)
48+
uses: actions/checkout@v4 # Checks out the repository code into the runner for the workflow to use.
49+
with:
50+
fetch-depth: 1 # Fetch only the latest commit for faster checkouts.
51+
52+
# Step 2: Set up the specified Python version and cache pip dependencies for faster builds.
53+
- name: Set Up Python ${{ env.PY_BUILD }}
54+
uses: actions/setup-python@v5
55+
with:
56+
python-version: ${{ env.PY_BUILD }} # Sets up the Python version specified in the environment variables.
57+
cache: 'pip' # Caches pip dependencies to speed up subsequent builds.
58+
59+
# Step 3: Install the project's Python dependencies.
60+
- name: Install Python Dependencies
61+
run: |
62+
echo "Installing Coeus..."
63+
python -m pip install --upgrade pip
64+
pip install -U git+https://github.com/xames3/coeus-sphinx-theme.git#egg=coeus-sphinx-theme
65+
66+
# Step 4: Build the Sphinx documentation into HTML format.
67+
- name: Build Sphinx Documentation
68+
# -E: Rebuild all files, not just those that have changed.
69+
# -W: Treat warnings as errors.
70+
# -a: Write all output files (default only writes new and changed files).
71+
# -q: Run in quiet mode, with minimal output.
72+
run: |
73+
echo "Building Sphinx documentation..."
74+
sphinx-build -EWaq -b html ${{ env.SOURCE_DIR }} ${{ env.OUTPUT_DIR }}
75+
76+
# Step 5: Deploy the built HTML files to the specified branch (GitHub Pages).
77+
- name: DEV | Deploy to GitHub Pages
78+
uses: peaceiris/actions-gh-pages@v4
79+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
80+
with:
81+
github_token: ${{ secrets.GITHUB_TOKEN }} # Deploys to the gh-pages branch.
82+
publish_branch: ${{ env.PUBLISH_BRANCH }} # Uses the GitHub token for authentication.
83+
publish_dir: ${{ env.OUTPUT_DIR }} # Directory to publish (the output of the Sphinx build).
84+
force_orphan: false # Do not force an orphan commit, preserving commit history.
85+
enable_jekyll: false # Disables Jekyll processing on GitHub Pages, which is unnecessary for Sphinx-generated HTML.
86+
user_email: "github-actions[bot]@users.noreply.github.com" # Email to associate with the commit.
87+
user_name: "github-actions[bot]" # Name to associate with the commit.
88+
full_commit_message: ${{ github.event.head_commit.message }} # Use the commit message from the push event.
89+
90+
# Step 6: Provide response after deployment.
91+
- name: Notify Success
92+
if: success()
93+
run: echo "✅ Documentation successfully built and deployed to GitHub Pages (Dev)."
94+
- name: Notify Failure
95+
if: failure()
96+
run: echo "❌ Failed to build or deploy the documentation from the dev branch. Please check the logs."

‎.github/workflows/publish-feature-pages.yaml

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# TOPST SCHOOL's GitHub Pages Feature Branch Workflow
2+
# ===================================================
3+
#
4+
# Author: Akshay Mestry <xa@mes3.dev>
5+
# Created on: Sunday, September 01 2024
6+
# Last updated on: Sunday, September 01 2024
7+
8+
# Workflow name displayed in TOPST SCHOOL's "Actions" tab.
9+
name: FEAT | Build and Deploy Documents
10+
11+
# A workflow with the following "on" value will run when a "push" is made
12+
# to the "feature" branch or pull request is made to "dev" in the
13+
# workflow's repository. For example, the "push" event has a branches filter
14+
# that causes this workflow to run only when a push to a branch that
15+
# matches the branches filter occurs, in this case, the "dev" branch.
16+
on:
17+
push:
18+
branches:
19+
- "feature/**"
20+
pull_request:
21+
branches:
22+
- dev
23+
24+
# We're using permissions to modify the default permissions granted to
25+
# the ``GITHUB_TOKEN``, adding or removing access as required, so that we
26+
# only allow the minimum required access.
27+
permissions:
28+
contents: write # Only write permissions to the repository contents are needed for deployment.
29+
30+
# A map of variables that are available to the steps of all jobs in the workflow.
31+
env:
32+
OUTPUT_DIR: docs/build/ # Directory where Sphinx will output the built HTML files.
33+
SOURCE_DIR: docs/source/ # Directory containing the Sphinx source files (rST or MD).
34+
PUBLISH_BRANCH: gh-pages # Branch where the static site will be published.
35+
PY_BUILD: 3.12.1 # Python version to be used for building the documentation.
36+
37+
# We're using concurrency to ensure that only a single job or workflow
38+
# using the same concurrency group will run at a time.
39+
concurrency:
40+
group: ${{ github.ref }} # Groups by branch, so jobs in the same branch won't overlap.
41+
cancel-in-progress: true # Cancels any currently running jobs in the same group if a new one starts.
42+
43+
# A workflow run is made up of one or more jobs, which run in parallel by default.
44+
# The ``ubuntu-latest`` label currently uses the Ubuntu 22.04 runner image.
45+
jobs:
46+
build:
47+
runs-on: ubuntu-latest # Runs the job on the latest available Ubuntu runner.
48+
steps:
49+
# Step 1: Check out the code from the repository to the runner.
50+
- name: Checkout TOPST SCHOOL Code (Feature)
51+
uses: actions/checkout@v4 # Checks out the repository code into the runner for the workflow to use.
52+
with:
53+
fetch-depth: 1 # Fetch only the latest commit for faster checkouts.
54+
55+
# Step 2: Set up the specified Python version and cache pip dependencies for faster builds.
56+
- name: Set Up Python ${{ env.PY_BUILD }}
57+
uses: actions/setup-python@v5
58+
with:
59+
python-version: ${{ env.PY_BUILD }} # Sets up the Python version specified in the environment variables.
60+
cache: 'pip' # Caches pip dependencies to speed up subsequent builds.
61+
62+
# Step 3: Install the project's Python dependencies.
63+
- name: Install Python Dependencies
64+
run: |
65+
echo "Installing Coeus..."
66+
python -m pip install --upgrade pip
67+
pip install -U git+https://github.com/xames3/coeus-sphinx-theme.git#egg=coeus-sphinx-theme
68+
69+
# Step 4: Build the Sphinx documentation into HTML format.
70+
- name: Build Sphinx Documentation
71+
# -E: Rebuild all files, not just those that have changed.
72+
# -W: Treat warnings as errors.
73+
# -a: Write all output files (default only writes new and changed files).
74+
# -q: Run in quiet mode, with minimal output.
75+
run: |
76+
echo "Building Sphinx documentation..."
77+
sphinx-build -EWaq -b html ${{ env.SOURCE_DIR }} ${{ env.OUTPUT_DIR }}

‎.github/workflows/publish-pages.yaml renamed to ‎.github/workflows/publish-main-pages.yaml

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,22 @@
1-
# TOPST SCHOOL's GitHub Pages Publishing Workflow
2-
# ===============================================
1+
# TOPST SCHOOL's GitHub Pages Main Branch Publishing Workflow
2+
# ===========================================================
33
#
44
# Author: Akshay Mestry <xa@mes3.dev>
5-
# Created on: Friday, August 30 2024
5+
# Created on: Sunday, September 01 2024
66
# Last updated on: Sunday, September 01 2024
77

88
# Workflow name displayed in TOPST SCHOOL's "Actions" tab.
9-
name: Build and Deploy TOPST SCHOOL Documentation
9+
name: MAIN | Build and Deploy Documents
1010

11-
# A workflow with the following "on" value will run when a "push" and
12-
# "pull_request" is made to the "main" branch in the workflow's repository.
13-
# For example, the "push" event has a branches filter that causes this
14-
# workflow to run only when a push to a branch that matches the branches
15-
# filter occurs, in this case, the "main" branch.
11+
# A workflow with the following "on" value will run when a "push" is made
12+
# to the "main" branch in the workflow's repository. For example, the "push"
13+
# event has a branches filter that causes this workflow to run only when
14+
# a push to a branch that matches the branches filter occurs, in this
15+
# case, the "main" branch.
1616
on:
1717
push:
1818
branches:
1919
- main
20-
pull_request:
21-
branches:
22-
- main
23-
workflow_dispatch: # Allows manual triggering of the workflow from the GitHub UI.
2420

2521
# We're using permissions to modify the default permissions granted to
2622
# the ``GITHUB_TOKEN``, adding or removing access as required, so that we
@@ -48,7 +44,7 @@ jobs:
4844
runs-on: ubuntu-latest # Runs the job on the latest available Ubuntu runner.
4945
steps:
5046
# Step 1: Check out the code from the repository to the runner.
51-
- name: Checkout TOPST SCHOOL Code
47+
- name: Checkout TOPST SCHOOL Code (Main)
5248
uses: actions/checkout@v4 # Checks out the repository code into the runner for the workflow to use.
5349
with:
5450
fetch-depth: 1 # Fetch only the latest commit for faster checkouts.
@@ -78,7 +74,7 @@ jobs:
7874
sphinx-build -EWaq -b html ${{ env.SOURCE_DIR }} ${{ env.OUTPUT_DIR }}
7975
8076
# Step 5: Deploy the built HTML files to the specified branch (GitHub Pages).
81-
- name: Deploy TOPST SCHOOL Documentation to GitHub Pages
77+
- name: MAIN | Deploy to GitHub Pages
8278
uses: peaceiris/actions-gh-pages@v4
8379
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
8480
with:
@@ -94,7 +90,7 @@ jobs:
9490
# Step 6: Provide response after deployment.
9591
- name: Notify Success
9692
if: success()
97-
run: echo "✅ Documentation successfully built and deployed to GitHub Pages."
93+
run: echo "✅ Documentation successfully built and deployed to GitHub Pages (Main)."
9894
- name: Notify Failure
9995
if: failure()
100-
run: echo "❌ Failed to build or deploy the documentation. Please check the logs."
96+
run: echo "❌ Failed to build or deploy the documentation from the main branch. Please check the logs."

0 commit comments

Comments
 (0)