Seems there is no books for incus , epub docs is okay ,thanks !
The Incus documentation uses Sphinx, Sphinx — Sphinx documentation and Sphinx has the facility to also export to epub. It should be easy to generate epub documents by running the epub builder.
This will require from you to get the source code of Incus, and figure out how to invoke the build system to generate epub output. Within the source code of Incus, the documentation is in the doc/ directory.
Sphinx supports the output of different formats for the documentation. The output of epub is built-in into Sphinx, while other options require extensions.
I did try, and I never got it to work. I used the command “sphinx-build -b epub ./ ../thomas.epub” on the cli (assuming I was in the doc directory. I did install the required sphinx and modules it complained about. Got the error:
Loaded Extensions
=================
None.
Traceback
=========
File "/home/tmunn/.local/share/mise/installs/python/3.15-dev/lib/python3.15/site-packages/sphinx/config.py", line 354, in read
raise ConfigError(
__("config directory doesn't contain a conf.py file (%s)") % confdir
)
sphinx.errors.ConfigError: config directory doesn't contain a conf.py file (/home/tmunn/src/incus)
The full traceback has been saved in:
/tmp/sphinx-err-trdruuwh.log
To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
⋊> ~/s/incus on main ◦ cd doc/ 12:47:25
⋊> ~/s/i/doc on main ◦ sphinx-build -b epub ./ ../thomas.epub 12:47:32
Running Sphinx v8.2.3
Using /home/tmunn/go/bin/incus to generate man pages.
loading translations [en]... done
Extension error!
Versions
========
* Platform: linux; (Linux-6.1.0-40-amd64-x86_64-with-glibc2.36)
* Python version: 3.15.0a0 (CPython)
* Sphinx version: 8.2.3
* Docutils version: 0.21.2
* Jinja2 version: 3.1.6
* Pygments version: 2.19.2
Last Messages
=============
None.
Loaded Extensions
=================
None.
Traceback
=========
File "/home/tmunn/.local/share/mise/installs/python/3.15-dev/lib/python3.15/site-packages/sphinx/registry.py", line 544, in load_extension
raise ExtensionError(
__('Could not import extension %s') % extname, err
) from err
sphinx.errors.ExtensionError: Could not import extension config-options (exception: No module named 'config-options')
The full traceback has been saved in:
/tmp/sphinx-err-_14umqif.log
To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
I figure it out. go to the “docs/.sphinx diretory (after typing in make docs)” and do a pip install -r requirements.txt. Then you have to do some zip magic to get the final uncompressed directory into a final compiled .zip file which is a .epub.
Its a bit of a PITA would be a nice feature!
If you prepare a build environment for Incus and manage to build the software, then you can also do the following, which will produce the standard HTML output.
$ make doc
...
dumping object inventory... done
build succeeded.
The HTML pages are in doc/html.
$
Therefore, you can edit the Makefile to add a target to generate epub output. Here’s an example.
diff --git a/Makefile b/Makefile
index 15ff75c5c..8ca38ca1a 100644
--- a/Makefile
+++ b/Makefile
@@ -178,6 +178,10 @@ doc-spellcheck: doc
doc-linkcheck: doc-setup
. $(SPHINXENV) ; LOCAL_SPHINX_BUILD=True sphinx-build -c doc/ -b linkcheck doc/ doc/html/ -d doc/.sphinx/.doctrees
+.PHONY: doc-linkcheck
+doc-epub: doc-setup
+ . $(SPHINXENV) ; LOCAL_SPHINX_BUILD=True sphinx-build -c doc/ -b epub doc/ doc/epub/ -d doc/.sphinx/.doctrees
+
.PHONY: doc-lint
doc-lint:
doc/.sphinx/.markdownlint/doc-lint.sh
Then,
$ make doc-epub
...
writing Incus.epub file...
build succeeded, 2 warnings.
The ePub file is in doc/epub.
$
Create a ZIP file of the contents of doc/epub and you have your incus.epub.
It would be perfect if it is added to each release . 
I never got used to reading technical documentation from an epub. What do you use on a desktop to read epubs? I have Calibre and opened the incus.epub file in there. But I cannot get used to the issue that a mere click will jump to some other location of the document and you are then lost. Am I doing it wrong?
I suppose if there is interest for an epub version of the documentation, that’s very easy to produce it. A more difficult issue is where to put it so people can find it. The HTML documentation is at Incus documentation
I often like to read the technical documentation on my rather large e-reader. So it would be nice to have an ePub version that I could simply download to it. It could even be included in the release file since the epub isn’t really that large.
We could add a doc.incus-6.17.tar.gz file at Release Incus 6.17 · lxc/incus · GitHub that has the offline documentation of Incus. This should include HTML, epub, and PDF. I tried to build the PDF but I am getting issues with the sphinx support for SVG for Texlive.
$ pdflatex incus.tex
...
LaTeX Warning: Hyper reference `explanation/instances:expl-instances' on page 1
1 undefined on input line 742.
! LaTeX Error: Unknown graphics extension: .svg.
See the LaTeX manual or LaTeX Companion for explanation.
Type H <return> for immediate help.
...
l.842 ...s{{application-vs-system-containers}.svg}
? x
</usr/share/texlive/texmf-dist/fonts/type1/public/amsfonts/cm/cmmi5.pfb></usr/s
hare/texlive/texmf-dist/fonts/type1/public/amsfonts/cm/cmsy5.pfb></usr/share/te
xmf/fonts/type1/public/tex-gyre/qhvb.pfb></usr/share/texmf/fonts/type1/public/t
ex-gyre/qtmb.pfb></usr/share/texmf/fonts/type1/public/tex-gyre/qtmr.pfb></usr/s
hare/texmf/fonts/type1/public/tex-gyre/qtmri.pfb></usr/share/texlive/texmf-dist
/fonts/type1/public/txfonts/t1xtt.pfb>
Output written on incus.pdf (14 pages, 150547 bytes).
$
The issue is at
\sphinxAtStartPar
\sphinxincludegraphics{{application-vs-system-containers}.svg}
This requires to add an extension to Sphinx.
Open doc/conf.py and add 'sphinx.ext.imgconverter' to the list of existing extentions.
extensions = [
'sphinx.ext.imgconverter',
]
By doing so, it generates a 513 page PDF until it stops again with the following.
LaTeX Warning: Hyper reference `reference/storage_dir:storage_volume_dir-common
:snapshots.expiry.manual' on page 514 undefined on input line 51338.
Runaway argument?
{ \sphinxAtStartPar Pongo2 template string that represents the snapsh\ETC.
! Paragraph ended before \DUrole was complete.
<to be read again>
\par
l.51373
?
The Sphinx output gives a lot of warnings on undefined references and should be looked into.
I think it would be good to produce such documentation as a separate release asset. I am not sure if we should wait to resolve the PDF generation issues.
I am sending to both of you the epub file for testing to make sure that it is indeed usable.