Skip to content

Commit 3d9c06c

Browse files
woxxywoxxy
committed
docs: modernize Sphinx docs with Furo and GitHub Pages workflow
1 parent b0ebfb8 commit 3d9c06c

8 files changed

Lines changed: 159 additions & 34 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Documentation
2+
3+
on:
4+
workflow_dispatch:
5+
pull_request:
6+
paths:
7+
- docs/**
8+
- README.md
9+
- .github/workflows/docs.yml
10+
push:
11+
branches:
12+
- master
13+
paths:
14+
- docs/**
15+
- README.md
16+
- .github/workflows/docs.yml
17+
18+
permissions:
19+
contents: read
20+
21+
concurrency:
22+
group: docs-${{ github.workflow }}-${{ github.ref }}
23+
cancel-in-progress: true
24+
25+
jobs:
26+
build:
27+
runs-on: ubuntu-latest
28+
29+
steps:
30+
- name: Checkout
31+
uses: actions/checkout@v4
32+
33+
- name: Setup Python
34+
uses: actions/setup-python@v5
35+
with:
36+
python-version: "3.12"
37+
38+
- name: Configure GitHub Pages
39+
if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
40+
uses: actions/configure-pages@v5
41+
42+
- name: Install docs dependencies
43+
run: |
44+
python -m pip install --upgrade pip
45+
pip install -r docs/requirements.txt
46+
47+
- name: Build docs
48+
run: sphinx-build --fail-on-warning --keep-going -b html docs docs/_build/html
49+
50+
- name: Upload docs artifact (PR/debug)
51+
if: always()
52+
uses: actions/upload-artifact@v4
53+
with:
54+
name: docs-html
55+
path: docs/_build/html
56+
if-no-files-found: error
57+
58+
- name: Upload Pages artifact
59+
if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
60+
uses: actions/upload-pages-artifact@v3
61+
with:
62+
path: docs/_build/html
63+
64+
deploy:
65+
if: github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
66+
needs: build
67+
runs-on: ubuntu-latest
68+
permissions:
69+
pages: write
70+
id-token: write
71+
environment:
72+
name: github-pages
73+
url: ${{ steps.deployment.outputs.page_url }}
74+
75+
steps:
76+
- name: Deploy to GitHub Pages
77+
id: deployment
78+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ Query Builder for SphinxQL
22
==========================
33

44
[![CI](https://github.com/FoolCode/SphinxQL-Query-Builder/actions/workflows/ci.yml/badge.svg)](https://github.com/FoolCode/SphinxQL-Query-Builder/actions/workflows/ci.yml)
5+
[![Documentation](https://github.com/FoolCode/SphinxQL-Query-Builder/actions/workflows/docs.yml/badge.svg)](https://github.com/FoolCode/SphinxQL-Query-Builder/actions/workflows/docs.yml)
56
[![Latest Stable Version](https://poser.pugx.org/foolz/sphinxql-query-builder/v/stable)](https://packagist.org/packages/foolz/sphinxql-query-builder)
67
[![Latest Unstable Version](https://poser.pugx.org/foolz/sphinxql-query-builder/v/unstable)](https://packagist.org/packages/foolz/sphinxql-query-builder)
78
[![Total Downloads](https://poser.pugx.org/foolz/sphinxql-query-builder/downloads)](https://packagist.org/packages/foolz/sphinxql-query-builder)
@@ -28,6 +29,20 @@ The majority of the methods in the package have been unit tested.
2829

2930
Helper methods and engine compatibility scenarios are covered by the test suite.
3031

32+
## Documentation
33+
34+
The docs are built with modern Sphinx + Furo styling.
35+
36+
Build locally:
37+
38+
```bash
39+
python3 -m pip install -r docs/requirements.txt
40+
sphinx-build --fail-on-warning --keep-going -b html docs docs/_build/html
41+
```
42+
43+
CI builds docs for pull requests and deploys the rendered site to GitHub Pages
44+
on pushes to `master`.
45+
3146
## How to Contribute
3247

3348
### Pull Requests

‎docs/_static/custom.css‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
:root {
2+
--color-brand-primary: #1c7ed6;
3+
--color-brand-content: #1864ab;
4+
}
5+
6+
.sidebar-brand-text {
7+
font-weight: 700;
8+
letter-spacing: 0.01em;
9+
}

‎docs/_templates/.gitkeep‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+

‎docs/conf.py‎

Lines changed: 36 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,40 @@
1-
# -*- coding: utf-8 -*-
2-
import sys, os
3-
sys.path.insert(0, os.path.abspath('.'))
1+
from datetime import date
42

5-
#needs_sphinx = '1.0'
3+
project = "SphinxQL Query Builder"
4+
author = "FoolCode"
5+
copyright = f"2012-{date.today().year}, {author}"
66

7-
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
8-
9-
templates_path = ['_templates']
10-
11-
source_suffix = '.rst'
12-
master_doc = 'index'
13-
14-
# General information about the project.
15-
project = u'SphinxQL Query Builder'
16-
copyright = u'2012-2015, FoolCode'
17-
18-
version = '1.0.0'
7+
# We track release notes in CHANGELOG.md and do not hardcode package versions here.
8+
version = "4.x"
199
release = version
2010

21-
exclude_patterns = ['_build', 'html', 'doctrees']
22-
add_function_parentheses = True
23-
add_module_names = True
24-
show_authors = False
25-
pygments_style = 'sphinx'
26-
modindex_common_prefix = ['foolfuuka']
27-
html_theme = 'default'
28-
html_static_path = ['_static']
29-
htmlhelp_basename = 'FoolFuukaDoc'
30-
31-
from sphinx.highlighting import lexers
32-
from pygments.lexers.web import JsonLexer
33-
from pygments.lexers.web import PhpLexer
34-
35-
lexers['json'] = JsonLexer(startinline=True)
36-
lexers['php'] = PhpLexer(startinline=True)
11+
extensions = [
12+
"sphinx.ext.autodoc",
13+
"sphinx.ext.viewcode",
14+
"sphinx.ext.githubpages",
15+
"sphinx_copybutton",
16+
]
17+
18+
templates_path = ["_templates"]
19+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
20+
21+
source_suffix = {".rst": "restructuredtext"}
22+
root_doc = "index"
23+
language = "en"
24+
25+
pygments_style = "sphinx"
26+
pygments_dark_style = "monokai"
27+
28+
html_theme = "furo"
29+
html_title = "SphinxQL Query Builder Documentation"
30+
html_static_path = ["_static"]
31+
html_css_files = ["custom.css"]
32+
html_theme_options = {
33+
"source_repository": "https://github.com/FoolCode/SphinxQL-Query-Builder/",
34+
"source_branch": "master",
35+
"source_directory": "docs/",
36+
"navigation_with_keys": True,
37+
}
38+
39+
copybutton_prompt_text = r">>> |\.\.\. |\$ "
40+
copybutton_prompt_is_regexp = True

‎docs/contribute.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,18 @@ Testing
2020

2121
All pull requests must be accompanied with passing tests and code coverage. The SphinxQL Query Builder uses `PHPUnit <https://github.com/sebastianbergmann/phpunit/>`_ for testing.
2222

23+
Documentation
24+
-------------
25+
26+
Documentation is built with Sphinx and the Furo theme.
27+
28+
Build locally:
29+
30+
.. code-block:: bash
31+
32+
python3 -m pip install -r docs/requirements.txt
33+
sphinx-build --fail-on-warning --keep-going -b html docs docs/_build/html
34+
2335
Issue Tracker
2436
-------------
2537

‎docs/index.rst‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1-
Welcome
2-
=======
1+
SphinxQL Query Builder
2+
======================
3+
4+
Modern PHP query builder documentation for SphinxQL and ManticoreQL.
35

46
.. toctree::
7+
:caption: Contents
58
:maxdepth: 2
69

710
intro

‎docs/requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
sphinx>=8.2.0,<10
2+
furo>=2025.9.25
3+
sphinx-copybutton>=0.5.2

0 commit comments

Comments
 (0)