Skip to content

Commit 9af73d4

Browse files
skjnldsvskjnldsv
authored
Merge pull request #14975 from nextcloud/backport/14971/stable34
[stable34] feat: add epub output for all three manuals (NC32+)
2 parents b9eebd2 + bee8c9e commit 9af73d4

6 files changed

Lines changed: 102 additions & 23 deletions

File tree

‎.github/workflows/sphinxbuild.yml‎

Lines changed: 72 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,58 @@ jobs:
7777
name: ${{ matrix.manual.name }}
7878
path: ${{ matrix.manual.directory }}/${{ matrix.manual.build_path }}
7979

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

228280
outputs:
@@ -363,13 +415,13 @@ jobs:
363415
fi
364416
done
365417
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}/"
418+
# Move PDF and ePub files to the root of the branch folder for cleaner structure
419+
echo "Looking for PDF and ePub files to move..."
420+
find "stage/${branch}/" -maxdepth 2 \( -name "*.pdf" -o -name "*.epub" \) -type f
421+
for f in "stage/${branch}"/*/*.pdf "stage/${branch}"/*/*.epub; do
422+
if [ -f "$f" ]; then
423+
echo "Moving: $f"
424+
mv "$f" "stage/${branch}/"
373425
fi
374426
done
375427
@@ -498,13 +550,13 @@ jobs:
498550
fi
499551
done
500552
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}/
553+
# Copy PDF and ePub files to the root of the branch folder
554+
echo "Looking for PDF and ePub files to copy..."
555+
find stage/${branch}/ -maxdepth 1 \( -name "*.pdf" -o -name "*.epub" \) -type f
556+
for f in stage/${branch}/*.pdf stage/${branch}/*.epub; do
557+
if [ -f "$f" ]; then
558+
echo "Copying: $f"
559+
cp "$f" server/${branch}/
508560
fi
509561
done
510562
@@ -641,8 +693,8 @@ jobs:
641693
fi
642694
done
643695
644-
# PDF files (kept at root of deploy dir)
645-
find "stage/${branch}" -maxdepth 1 -name "*.pdf" -exec cp {} netlify-deploy/ \;
696+
# PDF and ePub files (kept at root of deploy dir)
697+
find "stage/${branch}" -maxdepth 1 \( -name "*.pdf" -o -name "*.epub" \) -exec cp {} netlify-deploy/ \;
646698
647699
# Minimal root index linking to the deployed content
648700
cat > netlify-deploy/index.html <<'EOF'
@@ -660,8 +712,9 @@ jobs:
660712
<li><a href="admin_manual/">Administration Manual</a></li>
661713
<li><a href="developer_manual/">Developer Manual</a></li>
662714
<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>
715+
<li><a href="Nextcloud_User_Manual.pdf">User Manual PDF</a> / <a href="Nextcloud_User_Manual.epub">ePub</a></li>
716+
<li><a href="Nextcloud_Server_Administration_Manual.pdf">Administration Manual PDF</a> / <a href="Nextcloud_Server_Administration_Manual.epub">ePub</a></li>
717+
<li><a href="Nextcloud_Developer_Manual.epub">Developer Manual ePub</a></li>
665718
</ul>
666719
</body>
667720
</html>

‎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/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"

‎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)