.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DH_SPHINXDOC 1"
.TH DH_SPHINXDOC 1 2024-05-10 "" Debhelper
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
dh_sphinxdoc \- helps with packaging Sphinx\-generated documentation
.SH SYNOPSIS
.IX Header "SYNOPSIS"
dh_sphinxdoc [\fIdebhelper\ options\fR] [\fB\-X\fR\fIitem\fR] [\fIdirectory\fR...]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBdh_sphinxdoc\fR is a debhelper program that prepares Sphinx-generated
documentation for inclusion in a Debian package. More specifically:
.IP \(bu 4
It checks if all the files referenced by \fIsearchindex.js\fR exist.
.IP \(bu 4
It replaces known \fI*.js\fR files with symlinks to \fI/usr/share/javascript/sphinxdoc/\fR
and generates \fB${sphinxdoc:Depends}\fR substitution variable.
.IP \(bu 4
If the Sphinx RTD theme is used, it replaces known files from this theme with
symlinks to \fI/usr/share/sphinx_rtd_theme/\fR, and adds \fBsphinx-rtd-theme-common\fR
to \fB${sphinxdoc:Depends}\fR.
.IP \(bu 4
It provides a \fB${sphinxdoc:Built\-Using}\fR substitution variable, for tracking
files which could not be symlinked. Examples of such files are \fI*.js\fR and \fI*.css\fR
files that are generated from corresponding \fI*.js_t\fR and \fI*.css_t\fR templates,
and can vary depending on the used theme options (for instance, \fIbasic.css\fR file
is generated from \fIbasic.css_t\fR and is included in almost every Sphinx-generated
documentation). Currently, this variable will contain \fBsphinx\fR and, if the default
theme is used, \fBalabaster\fR, with their versions (other themes are not supported).
.IP \(bu 4
It removes the \fI.doctrees\fR directory.
.IP \(bu 4
It removes the \fI.buildinfo\fR file.
.IP \(bu 4
It removes the \fIwebsupport.js\fR file.
.PP
Note that \fBdh_sphinxdoc\fR does not build the documentation, it only performs
the above operations when the documentation is already installed into the
package build path. To build the docs, please use \fBsphinx\-build\fR\|(1) command
or \fBpython3 \-m sphinx\fR syntax.
.PP
You can pass \fB\-\-with sphinxdoc\fR to \fBdh\fR\|(1) to make it automatically call
\&\fBdh_sphinxdoc\fR after \fBdh_installdocs\fR.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fIdirectory\fR 4
.IX Item "directory"
By default, \fBdh_sphinxdoc\fR scans your package looking for directories looking
like they contain Sphinx-generated documentation. However, if you explicitly
provide one or more directories, only they will be processed. If documentation
is not found at \fIdirectory\fR, an error is raised.
.IP "\fB\-X\fR\fIitem\fR, \fB\-\-exclude=\fR\fIitem\fR" 4
.IX Item "-Xitem, --exclude=item"
Exclude files that contain \fIitem\fR anywhere in their filename from
being symlinked, removed or checked for existence.
.SH BUGS
.IX Header "BUGS"
Symlinking translations.js is not supported.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdebhelper\fR\|(7), \fBdh\fR\|(1).
.PP
This program is meant to be used together with debhelper.
.SH AUTHOR
.IX Header "AUTHOR"
Jakub Wilk <jwilk@debian.org>