Update to latest sphinx and add subtitle (#220)

* re-enable subtitle for the `User Guide`

* bump `sphinx` version and pin to 8.0.2, remove obsolete `sphinx-rtd-theme`

.github/workflows/documentation.yaml

@@ -59,7 +59,7 @@ jobs:
       - uses: actions/setup-python@v5
       - name: Install dependencies
         run: |
-          pip install setuptools_scm sphinx==7.2.5 piccolo-theme sphinx_rtd_theme myst_parser rst2pdf sphinx_togglebutton sphinx-argparse sphinx_copybutton sphinxcontrib-bibtex
+          pip install setuptools_scm sphinx==8.0.2 piccolo-theme myst_parser rst2pdf sphinx_togglebutton sphinx-argparse sphinx_copybutton sphinxcontrib-bibtex
           sudo apt clean
           sudo apt-get update
           sudo apt-get install --fix-missing -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra texlive-luatex texlive-xetex

website/conf.py

@@ -88,20 +88,21 @@
 guide_prefix = 'pypop-guide-' + release # include version in PDF filename
 guide_name = 'PyPop User Guide'
 guide_subtitle = 'User Guide for Python for Population Genomics'
-guide_name_with_subtitle = "%s \\\\{\\LARGE %s}" % (guide_name, guide_subtitle)
+guide_name_with_subtitle = "%s: %s" % (guide_name, guide_subtitle)
 guide_pdf_link = "`PDF <../%s.pdf>`__" % guide_prefix
 
 #from PyPop import __pkgname__
 # other substitutions
 rst_epilog = """
 .. |pkgname| replace:: %s
+.. |guide_subtitle| replace:: **%s**
 .. |htmlauthor| replace:: %s 
 .. |full_release| replace:: %s
 .. |uc_copyright| replace:: %s
 .. |copyright| replace:: %s
 .. |gfdl_license_text| replace:: %s
 .. |guide_pdf_link| replace:: %s
-""" % ("``pypop-genomics``", htmlauthor, full_release, uc_copyright, copyright, gfdl_license_text, guide_pdf_link)
+""" % ("``pypop-genomics``", guide_subtitle, htmlauthor, full_release, uc_copyright, copyright, gfdl_license_text, guide_pdf_link)
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -254,20 +255,9 @@ def __init__(self, **options):
 #latex_show_urls = 'inline'
 latex_show_urls = 'footnote'
 
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
+# need to declare a template for the LaTeX preamble for later substitution
 
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # make PDF shorter by allowing chapters to start immediately
-    'extraclassoptions': 'openany,oneside',
-    # Additional stuff for the LaTeX preamble.
-    #
-    'preamble': r'''\DeclareRobustCommand{\and}{%
+my_latex_preamble_template = r'''\DeclareRobustCommand{\and}{%
 \end{tabular}\kern-\tabcolsep\\\begin{tabular}[t]{c}%
 }%
 \setcounter{secnumdepth}{1}%
@@ -300,13 +290,76 @@ def __init__(self, **options):
    \vfill
    \endgroup
   }{}
-}{}{}''',
+}{}{}
+
+% override default title page to add subtitle
+\makeatletter
+\renewcommand{\sphinxmaketitle}{%
+  \let\sphinxrestorepageanchorsetting\relax
+  \ifHy@pageanchor\def\sphinxrestorepageanchorsetting{\Hy@pageanchortrue}\fi
+  \hypersetup{pageanchor=false}% avoid duplicate destination warnings
+  \begin{titlepage}%
+    \let\footnotesize\small
+    \let\footnoterule\relax
+    \noindent\rule{\textwidth}{1pt}\par
+      \begingroup % for PDF information dictionary
+       \def\endgraf{ }\def\and{\& }%
+       \pdfstringdefDisableCommands{\def\\{, }}% overwrite hyperref setup
+       \hypersetup{pdfauthor={\@author}, pdftitle={\@title}}%
+      \endgroup
+    \begin{flushright}%
+      \sphinxlogo
+      \py@HeaderFamily
+      {\Huge \@title \par}
+      {\Large SUBTITLE \par}
+      {\itshape\LARGE \py@release\releaseinfo \par}
+      \vfill
+      {\LARGE
+        \begin{tabular}[t]{c}
+          \@author
+        \end{tabular}\kern-\tabcolsep
+        \par}
+      \vfill\vfill
+      {\large
+       \@date \par
+       \vfill
+       \py@authoraddress \par
+      }%
+    \end{flushright}%\par
+    \@thanks
+  \end{titlepage}%
+  \setcounter{footnote}{0}%
+  \let\thanks\relax\let\maketitle\relax
+  %\gdef\@thanks{}\gdef\@author{}\gdef\@title{}
+  \clearpage
+  \ifdefined\sphinxbackoftitlepage\sphinxbackoftitlepage\fi
+  \if@openright\cleardoublepage\else\clearpage\fi
+  \sphinxrestorepageanchorsetting
+}'''
+
+# replace the template with the right SUBTITLE
+my_latex_preamble = my_latex_preamble_template.replace('SUBTITLE', guide_subtitle)
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # make PDF shorter by allowing chapters to start immediately
+    'extraclassoptions': 'openany,oneside',
+    # Additional stuff for the LaTeX preamble.
+    #
+    'preamble': my_latex_preamble,
 
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
 
-    'maketitle': r'\newcommand\sphinxbackoftitlepage{\sphinxstrong{%s}\\ \\%s. \\Copyright © %s. \\ \\%s \\ \\\emph{Document revision}: %s}\sphinxmaketitle' % (guide_name, uc_copyright, copyright, gfdl_license_text, full_release),
+    'maketitle': r'\newcommand\sphinxbackoftitlepage{\sphinxstrong{%s}\\ \\%s. \\Copyright © %s. \\ \\%s \\ \\\emph{Document revision}: %s}\sphinxmaketitle' % (guide_name_with_subtitle, uc_copyright, copyright, gfdl_license_text, full_release),
 
     # margins
     'sphinxsetup': 'hmargin=0.8in, vmargin={1in,0.9in}',

website/docs/index.rst

@@ -6,6 +6,8 @@ PyPop User Guide
 
 .. only:: html
 
+   |guide_subtitle|
+
    |htmlauthor|
 
    .. admonition:: *Documenting release*  |version|  *of PyPop*.