Skip to content

Commit 4276f2d

Browse files
rakeknivenrakekniven
authored
Merge branch 'master' into feature/ux-writing-guide
2 parents 20be492 + 8e60282 commit 4276f2d

18 files changed

Lines changed: 543 additions & 53 deletions

File tree

‎.github/workflows/generate-top-index.yml‎

Lines changed: 37 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -11,28 +11,22 @@ on:
1111
- master
1212

1313
permissions:
14-
contents: write
14+
contents: read
1515

1616
jobs:
1717
build-and-deploy:
1818
name: Build index.html
1919
runs-on: ubuntu-latest
2020

21-
steps:
22-
- name: Cache git metadata
23-
uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
24-
with:
25-
path: .git
26-
key: git-metadata-${{ github.sha }}
27-
restore-keys: |
28-
git-metadata-${{ github.sha }}
29-
git-metadata
21+
permissions:
22+
contents: write
23+
pull-requests: write
3024

31-
- name: Checkout Github Pages branch
25+
steps:
26+
- name: Checkout repository
3227
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
3328
with:
3429
fetch-depth: 0
35-
token: ${{ github.event_name == 'push' && secrets.COMMAND_BOT_PAT || github.token }}
3630

3731
- name: Get stable branches
3832
id: branch
@@ -55,23 +49,42 @@ jobs:
5549
cp /tmp/index.html build/index.html
5650
php build/verify-index.php
5751
58-
- name: Switch to gh-pages branch
52+
- name: Checkout gh-pages branch
5953
if: github.event_name == 'push'
60-
run: |
61-
git fetch origin gh-pages
62-
git checkout gh-pages
63-
git config --local user.email "nextcloud-command@users.noreply.github.com"
64-
git config --local user.name "nextcloud-command"
65-
66-
- name: Commit and push changes
54+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
55+
with:
56+
ref: gh-pages
57+
fetch-depth: 1
58+
persist-credentials: false
59+
60+
- name: Apply generated files to gh-pages
6761
if: github.event_name == 'push'
6862
run: |
69-
# Move the generated index.html and static files to the root of the gh-pages branch
7063
rm -rf index.html static/
7164
mv /tmp/index.html index.html
7265
mv /tmp/static/ static/
73-
git add index.html static/
74-
git commit -m "chore: update index.html for documentation" || echo "No changes to commit"
75-
git push origin gh-pages || echo "Nothing to push (expected if no changes)"
66+
67+
- name: Create Pull Request for index deployment
68+
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
69+
id: cpr
70+
if: github.event_name == 'push'
71+
with:
72+
token: ${{ secrets.COMMAND_BOT_PAT }}
73+
commit-message: "chore: update index.html for documentation"
74+
committer: nextcloud-command <nextcloud-command@users.noreply.github.com>
75+
author: nextcloud-command <nextcloud-command@users.noreply.github.com>
76+
signoff: true
77+
branch: "automated/deploy/documentation-index"
78+
base: gh-pages
79+
title: "Documentation index update"
80+
body: |
81+
This PR was automatically generated by the CI workflow and
82+
includes the latest changes to the documentation index.
83+
delete-branch: true
84+
labels: "automated, 3. to review"
85+
86+
- name: Enable Pull Request Automerge
87+
run: gh pr merge --merge --auto "${{ steps.cpr.outputs.pull-request-number }}"
88+
if: steps.cpr.outputs.pull-request-number != ''
7689
env:
7790
GH_TOKEN: ${{ secrets.COMMAND_BOT_PAT }}

‎.github/workflows/labeling.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ jobs:
2525

2626
steps:
2727
- name: Apply labels based on changed files
28-
uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b # v6.0.1
28+
uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213 # v6.1.0
2929
with:
3030
repo-token: ${{ secrets.GITHUB_TOKEN }}
3131
sync-labels: false

‎.github/workflows/sphinxbuild.yml‎

Lines changed: 80 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ on:
66
branches:
77
- master
88
- stable*
9+
schedule:
10+
- cron: '0 2 * * *' # 02:00 UTC daily — full build + deploy
911

1012
permissions:
1113
contents: read
@@ -77,6 +79,58 @@ jobs:
7779
name: ${{ matrix.manual.name }}
7880
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
7981

82+
# ============================================================================
83+
# BUILD EPUB
84+
# ============================================================================
85+
# Builds epub documentation for all three manuals. No LaTeX required —
86+
# runs in the same plain Python environment as build-html.
87+
# ============================================================================
88+
build-epub:
89+
name: Building ${{ matrix.manual.name }} ePub
90+
runs-on: ubuntu-latest
91+
92+
strategy:
93+
fail-fast: false
94+
matrix:
95+
manual:
96+
- name: "user_manual"
97+
directory: "user_manual"
98+
build_epub_path: "_build/epub/Nextcloud_User_Manual.epub"
99+
100+
- name: "admin_manual"
101+
directory: "admin_manual"
102+
build_epub_path: "_build/epub/Nextcloud_Server_Administration_Manual.epub"
103+
104+
- name: "developer_manual"
105+
directory: "developer_manual"
106+
build_epub_path: "_build/epub/Nextcloud_Developer_Manual.epub"
107+
108+
steps:
109+
- name: Checkout repository
110+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
111+
112+
- name: Set up Python
113+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
114+
with:
115+
python-version: "3.13"
116+
cache: "pip"
117+
118+
- name: Install pip dependencies
119+
run: python -m pip install -r requirements.txt
120+
121+
- name: Build epub documentation
122+
run: |
123+
set -e
124+
cd ${{ matrix.manual.directory }}
125+
make epub
126+
ls -la ${{ matrix.manual.build_epub_path }}
127+
128+
- name: Upload ePub documentation
129+
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
130+
with:
131+
name: ${{ matrix.manual.name }}-epub
132+
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_epub_path }}
133+
80134
# ============================================================================
81135
# PREPARE PDF IMAGE
82136
# ============================================================================
@@ -222,7 +276,7 @@ jobs:
222276
# ============================================================================
223277
stage-and-check:
224278
name: Stage and check documentation
225-
needs: [build-html, build-pdf]
279+
needs: [build-html, build-pdf, build-epub]
226280
runs-on: ubuntu-latest
227281

228282
outputs:
@@ -363,13 +417,13 @@ jobs:
363417
fi
364418
done
365419
366-
# Move PDF files to the root of the branch folder for cleaner structure
367-
echo "Looking for PDF files to move..."
368-
find "stage/${branch}/" -maxdepth 2 -name "*.pdf" -type f
369-
for pdf in "stage/${branch}"/*/*.pdf; do
370-
if [ -f "$pdf" ]; then
371-
echo "Moving PDF: $pdf"
372-
mv "$pdf" "stage/${branch}/"
420+
# Move PDF and ePub files to the root of the branch folder for cleaner structure
421+
echo "Looking for PDF and ePub files to move..."
422+
find "stage/${branch}/" -maxdepth 2 \( -name "*.pdf" -o -name "*.epub" \) -type f
423+
for f in "stage/${branch}"/*/*.pdf "stage/${branch}"/*/*.epub; do
424+
if [ -f "$f" ]; then
425+
echo "Moving: $f"
426+
mv "$f" "stage/${branch}/"
373427
fi
374428
done
375429
@@ -453,7 +507,7 @@ jobs:
453507
deploy:
454508
name: Deploy documentation for gh-pages
455509
needs: stage-and-check
456-
if: github.event_name == 'push'
510+
if: github.event_name == 'schedule'
457511
runs-on: ubuntu-latest
458512

459513
permissions:
@@ -498,13 +552,13 @@ jobs:
498552
fi
499553
done
500554
501-
# Move pdf files to the root of the branch folder
502-
echo "Looking for PDF files to copy..."
503-
find stage/${branch}/ -name "*.pdf" -type f
504-
for pdf in stage/${branch}/*.pdf; do
505-
if [ -f "$pdf" ]; then
506-
echo "Copying PDF: $pdf"
507-
cp "$pdf" server/${branch}/
555+
# Copy PDF and ePub files to the root of the branch folder
556+
echo "Looking for PDF and ePub files to copy..."
557+
find stage/${branch}/ -maxdepth 1 \( -name "*.pdf" -o -name "*.epub" \) -type f
558+
for f in stage/${branch}/*.pdf stage/${branch}/*.epub; do
559+
if [ -f "$f" ]; then
560+
echo "Copying: $f"
561+
cp "$f" server/${branch}/
508562
fi
509563
done
510564
@@ -641,8 +695,8 @@ jobs:
641695
fi
642696
done
643697
644-
# PDF files (kept at root of deploy dir)
645-
find "stage/${branch}" -maxdepth 1 -name "*.pdf" -exec cp {} netlify-deploy/ \;
698+
# PDF and ePub files (kept at root of deploy dir)
699+
find "stage/${branch}" -maxdepth 1 \( -name "*.pdf" -o -name "*.epub" \) -exec cp {} netlify-deploy/ \;
646700
647701
# Minimal root index linking to the deployed content
648702
cat > netlify-deploy/index.html <<'EOF'
@@ -660,8 +714,9 @@ jobs:
660714
<li><a href="admin_manual/">Administration Manual</a></li>
661715
<li><a href="developer_manual/">Developer Manual</a></li>
662716
<li><a href="user_manual/en/">User Manual (English)</a></li>
663-
<li><a href="Nextcloud_User_Manual.pdf">User Manual PDF</a></li>
664-
<li><a href="Nextcloud_Server_Administration_Manual.pdf">Administration Manual PDF</a></li>
717+
<li><a href="Nextcloud_User_Manual.pdf">User Manual PDF</a> / <a href="Nextcloud_User_Manual.epub">ePub</a></li>
718+
<li><a href="Nextcloud_Server_Administration_Manual.pdf">Administration Manual PDF</a> / <a href="Nextcloud_Server_Administration_Manual.epub">ePub</a></li>
719+
<li><a href="Nextcloud_Developer_Manual.epub">Developer Manual ePub</a></li>
665720
</ul>
666721
</body>
667722
</html>
@@ -802,7 +857,11 @@ jobs:
802857
then
803858
echo "This workflow ran for a pull request. We need stage-and-check and link-check to succeed, deploy must be skipped, and netlify-preview must succeed or fail (non-fatal on forks)"
804859
if ${{ needs.stage-and-check.result != 'success' || needs.link-check.result != 'success' || needs.deploy.result != 'skipped' || (needs.netlify-preview.result != 'success' && needs.netlify-preview.result != 'failure') }}; then exit 1; fi
860+
elif ${{ github.event_name == 'push' }}
861+
then
862+
echo "This workflow ran for a push. We need stage-and-check and link-check to succeed; deploy and netlify-preview must be skipped"
863+
if ${{ needs.stage-and-check.result != 'success' || needs.link-check.result != 'success' || needs.deploy.result != 'skipped' || needs.netlify-preview.result != 'skipped' }}; then exit 1; fi
805864
else
806-
echo "This workflow ran for a push. We need stage-and-check, link-check, and deploy to succeed; netlify-preview must be skipped"
865+
echo "This workflow ran on schedule. We need stage-and-check, link-check, and deploy to succeed; netlify-preview must be skipped"
807866
if ${{ needs.stage-and-check.result != 'success' || needs.link-check.result != 'success' || needs.deploy.result != 'success' || needs.netlify-preview.result != 'skipped' }}; then exit 1; fi
808867
fi

‎Makefile‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
all: html pdf
1+
all: html pdf epub
22

33
html: admin-manual-html user-manual-html developer-manual-html
44
pdf: admin-manual-pdf user-manual-pdf
5+
epub: admin-manual-epub user-manual-epub developer-manual-epub
56

67
admin-manual-html:
78
rm -rf admin_manual/_build/html/com
@@ -26,6 +27,18 @@ user-manual-pdf:
2627
cd user_manual && make latexpdf
2728
@echo "User manual build finished; PDF is updated"
2829

30+
admin-manual-epub:
31+
cd admin_manual && make epub
32+
@echo "Admin manual build finished; epub is updated"
33+
34+
user-manual-epub:
35+
cd user_manual && make epub
36+
@echo "User manual build finished; epub is updated"
37+
38+
developer-manual-epub: openapi-spec
39+
cd developer_manual && make epub
40+
@echo "Developer manual build finished; epub is updated"
41+
2942
get-server-sources:
3043
cd build && sh get-server-sources.sh $(DRONE_BRANCH)
3144

‎admin_manual/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@
7373
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output
7474

7575
epub_title = u'Nextcloud Server Administration Manual'
76+
epub_basename = u'Nextcloud_Server_Administration_Manual'
7677
epub_author = u'The Nextcloud developers'
7778
epub_publisher = u'The Nextcloud developers'
7879
epub_copyright = u'2012-2025, The Nextcloud developers'

‎build/server-block.php‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,16 +26,26 @@ function generate_section(string $version, ?int $index = null): string {
2626
$userManualUrl .= 'en/';
2727
}
2828

29+
$hasEpub = $version >= 32;
30+
$userManualDownloads = '<a class="reference external" href="server/' . $label . '/Nextcloud_User_Manual.pdf">PDF</a>';
31+
$adminManualDownloads = '<a class="reference external" href="server/' . $label . '/Nextcloud_Server_Administration_Manual.pdf">PDF</a>';
32+
$developerManualDownloads = '';
33+
if ($hasEpub) {
34+
$userManualDownloads .= ', <a class="reference external" href="server/' . $label . '/Nextcloud_User_Manual.epub">ePub</a>';
35+
$adminManualDownloads .= ', <a class="reference external" href="server/' . $label . '/Nextcloud_Server_Administration_Manual.epub">ePub</a>';
36+
$developerManualDownloads = ' (<a class="reference external" href="server/' . $label . '/Nextcloud_Developer_Manual.epub">ePub</a>)';
37+
}
38+
2939
return <<<HTML
3040
<div class="section" id="nextcloud-$label">
3141
<h2>Nextcloud $version<a class="headerlink" href="#nextcloud-$label" title="Permalink to this headline">¶</a></h2>
3242
$note
3343
<ul class="simple">
3444
<li><a class="reference external" href="$userManualUrl">User Manual</a>
35-
(<a class="reference external" href="server/$label/Nextcloud_User_Manual.pdf">Download PDF</a>)</li>
45+
($userManualDownloads)</li>
3646
<li><a class="reference external" href="server/$label/admin_manual/">Administration Manual</a>
37-
(<a class="reference external" href="server/$label/Nextcloud_Server_Administration_Manual.pdf">Download PDF</a>)</li>
38-
<li><a class="reference external" href="server/$label/developer_manual/">Developer Manual</a></li>
47+
($adminManualDownloads)</li>
48+
<li><a class="reference external" href="server/$label/developer_manual/">Developer Manual</a>$developerManualDownloads</li>
3949
</ul>
4050
</div>
4151
HTML;

‎developer_manual/client_apis/OCS/ocs-api-overview.rst‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,28 @@ It can be an option for filtering on a later stage but you can also leave them o
253253
254254
curl -i -u master -X GET -H "OCS-APIRequest: true" 'https://my.nextcloud/ocs/v2.php/core/autocomplete/get?search=JOANNE%40EMAIL.ISP&shareTypes[]=8&limit=2'
255255
256-
The shareType defaults to regular users if you left it out), the limit defaults to 10.
256+
The ``shareTypes`` parameter filters results by share type. If omitted, it defaults to regular
257+
users (``0``). The limit defaults to ``10``.
258+
259+
.. list-table::
260+
:header-rows: 1
261+
262+
* - Value
263+
- Share type
264+
* - ``0``
265+
- Users (default)
266+
* - ``1``
267+
- Groups
268+
* - ``4``
269+
- Email
270+
* - ``6``
271+
- Federated cloud shares
272+
* - ``7``
273+
- Circles
274+
* - ``8``
275+
- Guest accounts
276+
* - ``10``
277+
- Talk conversations
257278

258279
Filtering the auto-complete results
259280
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

‎developer_manual/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@
9292
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output
9393

9494
epub_title = "Nextcloud Developer Manual"
95+
epub_basename = "Nextcloud_Developer_Manual"
9596
epub_author = "The Nextcloud developers"
9697
epub_publisher = "The Nextcloud developers"
9798
epub_copyright = "2012-2024, The Nextcloud developers"

‎requirements.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ sphinxcontrib-devhelp==2.0.0
2727
sphinxcontrib-htmlhelp==2.1.0
2828
sphinxcontrib-jquery==4.1
2929
sphinxcontrib-jsmath==1.0.1
30-
sphinxcontrib-mermaid==2.0.1
30+
sphinxcontrib-mermaid==2.0.2
3131
sphinx-lint==1.0.2
3232
sphinx-notfound-page==1.1.0
3333
sphinxcontrib-phpdomain==0.15.2

‎user_manual/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@
8383
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-epub-output
8484

8585
epub_title = u'Nextcloud User Manual'
86+
epub_basename = u'Nextcloud_User_Manual'
8687
epub_author = u'The Nextcloud developers'
8788
epub_publisher = u'The Nextcloud developers'
8889
epub_copyright = u'2012-2025, The Nextcloud developers'

0 commit comments

Comments
 (0)