Skip to content

Commit bd4b5f6

Browse files
vitormattosvitormattos
committed
docs: add tested user docs site and github pages deploy
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
1 parent 7252fa2 commit bd4b5f6

46 files changed

Lines changed: 1607 additions & 120 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,14 @@ body:
99
id: summary
1010
attributes:
1111
label: Summary
12+
description: Provide a short, objective problem statement.
1213
validations:
1314
required: true
1415
- type: textarea
1516
id: steps
1617
attributes:
1718
label: Steps to reproduce
19+
description: Include exact input and commands.
1820
validations:
1921
required: true
2022
- type: textarea
@@ -23,3 +25,14 @@ body:
2325
label: Expected behavior
2426
validations:
2527
required: true
28+
- type: textarea
29+
id: actual
30+
attributes:
31+
label: Actual behavior
32+
validations:
33+
required: true
34+
- type: input
35+
id: runtime
36+
attributes:
37+
label: Runtime details
38+
placeholder: PHP version, package version/commit, OS

‎.github/ISSUE_TEMPLATE/commercial_support.yml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# SPDX-FileCopyrightText: 2026 LibreSign
2+
# SPDX-License-Identifier: AGPL-3.0-or-later
3+
4+
name: Commercial support
5+
description: Ask about paid support or sponsored prioritization
6+
labels: [support]
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for your interest in commercial support.
12+
13+
This template does not guarantee free consulting. Sponsored or paid work can help prioritize compatibility, features, and long-term maintenance.
14+
15+
Current public funding channel: https://github.com/sponsors/LibreSign
16+
- type: textarea
17+
id: context
18+
attributes:
19+
label: Project context
20+
description: Describe your use case, expected timeline, and technical scope.
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: requested_scope
25+
attributes:
26+
label: Requested support scope
27+
description: Include expected deliverables (for example SVG compatibility work, integration support, QA hardening).
28+
validations:
29+
required: true
30+
- type: input
31+
id: contact
32+
attributes:
33+
label: Preferred contact method
34+
placeholder: email or issue-based follow-up
35+
validations:
36+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,9 @@ contact_links:
66
- name: Security disclosure
77
url: https://github.com/LibreSign/xobject-template/security
88
about: Please report vulnerabilities privately.
9+
- name: Documentation site
10+
url: https://github.com/LibreSign/xobject-template/tree/main/docs
11+
about: Browse the user documentation source.
12+
- name: Sponsor maintenance
13+
url: https://github.com/sponsors/LibreSign
14+
about: Funding helps prioritize fixes and compatibility work.

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# SPDX-FileCopyrightText: 2026 LibreSign
2+
# SPDX-License-Identifier: AGPL-3.0-or-later
3+
4+
name: Documentation
5+
description: Report documentation errors or suggest improvements
6+
labels: [documentation]
7+
body:
8+
- type: textarea
9+
id: problem
10+
attributes:
11+
label: What is unclear or incorrect?
12+
validations:
13+
required: true
14+
- type: input
15+
id: page
16+
attributes:
17+
label: Affected page/path
18+
placeholder: docs/reference/supported-svg.md
19+
- type: textarea
20+
id: suggestion
21+
attributes:
22+
label: Suggested improvement
23+
description: Keep suggestions objective and user-focused.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,18 @@ body:
99
id: problem
1010
attributes:
1111
label: Problem statement
12+
description: Describe the user or integration problem first.
1213
validations:
1314
required: true
1415
- type: textarea
1516
id: proposal
1617
attributes:
1718
label: Proposed solution
19+
description: Keep scope explicit and include expected API/behavior impact.
1820
validations:
1921
required: true
22+
- type: textarea
23+
id: non_goals
24+
attributes:
25+
label: Non-goals / out of scope
26+
description: Clarify what should not be included.

‎.github/ISSUE_TEMPLATE/rendering_bug.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# SPDX-FileCopyrightText: 2026 LibreSign
2+
# SPDX-License-Identifier: AGPL-3.0-or-later
3+
4+
name: Rendering bug
5+
description: Report a minimal reproducible rendering issue for HTML/CSS/SVG to XObject output
6+
labels: [bug, rendering]
7+
body:
8+
- type: textarea
9+
id: summary
10+
attributes:
11+
label: Summary
12+
description: Describe the rendering issue in one or two sentences.
13+
validations:
14+
required: true
15+
- type: textarea
16+
id: minimal_input
17+
attributes:
18+
label: Minimal HTML/CSS/SVG input
19+
description: Paste the smallest possible input that reproduces the issue.
20+
render: markdown
21+
validations:
22+
required: true
23+
- type: textarea
24+
id: expected_output
25+
attributes:
26+
label: Expected output
27+
validations:
28+
required: true
29+
- type: textarea
30+
id: actual_output
31+
attributes:
32+
label: Actual output
33+
validations:
34+
required: true
35+
- type: textarea
36+
id: payload_details
37+
attributes:
38+
label: Generated content stream/resources (if possible)
39+
description: Include compile result content stream/resources snippet when available.
40+
- type: dropdown
41+
id: affected_area
42+
attributes:
43+
label: Affected area
44+
options:
45+
- text
46+
- PNG/JPEG
47+
- SVG
48+
- layout
49+
- CSS
50+
- interpolation
51+
- placement
52+
validations:
53+
required: true
54+
- type: input
55+
id: php_version
56+
attributes:
57+
label: PHP version
58+
placeholder: '8.2.x'
59+
validations:
60+
required: true
61+
- type: input
62+
id: package_version
63+
attributes:
64+
label: Package version or commit
65+
placeholder: 'composer version, tag, or commit hash'
66+
validations:
67+
required: true
68+
- type: textarea
69+
id: fixture
70+
attributes:
71+
label: Minimal fixture attachment details
72+
description: If possible, attach or describe a minimal fixture file set.

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,24 @@
1010
- [ ] Tests added/updated
1111
- [ ] Relevant checks executed
1212

13+
## Documentation
14+
15+
- [ ] Documentation updated
16+
- [ ] Examples updated if public behavior changed
17+
- [ ] Supported HTML/CSS/SVG matrix updated if relevant
18+
- [ ] Documentation drift checks pass
19+
1320
## Performance
1421

1522
- [ ] Performance impact assessed
1623
- [ ] Benchmark threshold still green
1724

25+
## Output integrity
26+
27+
- [ ] No unsupported feature documented as supported
28+
- [ ] No generated build artifacts committed to the source branch
29+
- [ ] LibreSign use case impact considered if relevant
30+
1831
## Compliance
1932

2033
- [ ] DCO sign-off in all commits

‎.github/pull_request_template.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<!-- SPDX-FileCopyrightText: 2026 LibreSign -->
2+
<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
3+
4+
## Scope
5+
6+
- [ ] Change scope and impact are clearly described
7+
8+
## Evidence
9+
10+
- [ ] Tests added/updated
11+
- [ ] Relevant checks executed
12+
13+
## Documentation
14+
15+
- [ ] Documentation updated
16+
- [ ] Examples updated if public behavior changed
17+
- [ ] Supported HTML/CSS/SVG matrix updated if relevant
18+
- [ ] Documentation drift checks pass
19+
20+
## Performance
21+
22+
- [ ] Performance impact considered
23+
24+
## Output integrity
25+
26+
- [ ] No unsupported feature documented as supported
27+
- [ ] No generated build artifacts committed to the source branch
28+
- [ ] LibreSign use case impact considered if relevant
29+
30+
## Compliance
31+
32+
- [ ] DCO sign-off in all commits
33+
- [ ] REUSE/SPDX metadata preserved
34+
- [ ] License compatibility reviewed

‎.github/workflows/docs.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# SPDX-FileCopyrightText: 2026 LibreSign
2+
# SPDX-License-Identifier: AGPL-3.0-or-later
3+
4+
name: docs
5+
6+
on:
7+
pull_request:
8+
push:
9+
branches: [main]
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
validate-docs:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- name: Checkout
19+
uses: actions/checkout@v6
20+
21+
- name: Detect minimum PHP from composer.json
22+
id: php_min
23+
run: |
24+
php_version=$(grep -Po '"php"\s*:\s*"\K[^"]+' composer.json | grep -Eo '[0-9]+\.[0-9]+' | head -n1)
25+
[[ -n "$php_version" ]] || { echo "Could not determine minimum PHP version"; exit 1; }
26+
echo "version=$php_version" >> "$GITHUB_OUTPUT"
27+
28+
- name: Setup PHP
29+
uses: shivammathur/setup-php@v2
30+
with:
31+
php-version: ${{ steps.php_min.outputs.version }}
32+
33+
- name: Setup Python
34+
uses: actions/setup-python@v6
35+
with:
36+
python-version: '3.12'
37+
38+
- name: Install Composer dependencies
39+
run: composer install --no-interaction --prefer-dist
40+
41+
- name: Install PHPUnit bin dependencies
42+
run: composer bin phpunit install --no-interaction --prefer-dist
43+
44+
- name: Install docs dependencies
45+
run: python -m pip install --upgrade pip && pip install -r requirements-docs.txt
46+
47+
# Pull requests only validate docs. No deployment from PRs.
48+
- name: Run docs tests
49+
run: composer run docs:test
50+
51+
deploy-docs:
52+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
53+
needs: validate-docs
54+
runs-on: ubuntu-latest
55+
permissions:
56+
contents: write
57+
steps:
58+
- name: Checkout
59+
uses: actions/checkout@v6
60+
61+
- name: Setup Python
62+
uses: actions/setup-python@v6
63+
with:
64+
python-version: '3.12'
65+
66+
- name: Install docs dependencies
67+
run: python -m pip install --upgrade pip && pip install -r requirements-docs.txt
68+
69+
- name: Build docs site
70+
run: python -m mkdocs build --strict
71+
72+
# Pushes to main publish docs to gh-pages branch.
73+
# Maintainers should configure GitHub Pages source as:
74+
# Deploy from branch -> gh-pages -> /root
75+
- name: Deploy site to gh-pages branch
76+
uses: peaceiris/actions-gh-pages@v4
77+
with:
78+
github_token: ${{ secrets.GITHUB_TOKEN }}
79+
publish_dir: ./site
80+
publish_branch: gh-pages
81+
force_orphan: true

0 commit comments

Comments
 (0)