From 66deab3237972f8073da53f2fb0642414c9af3bf Mon Sep 17 00:00:00 2001 From: Alex Lancaster Date: Sat, 14 Sep 2024 22:51:44 -0400 Subject: [PATCH] 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 | 2 +- website/conf.py | 87 ++++++++++++++++++++++------ website/docs/index.rst | 2 + 3 files changed, 73 insertions(+), 18 deletions(-) diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 544486577..001b3c818 100644 --- a/.github/workflows/documentation.yaml +++ b/.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 diff --git a/website/conf.py b/website/conf.py index e36e0ae61..3902659e6 100644 --- a/website/conf.py +++ b/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}', diff --git a/website/docs/index.rst b/website/docs/index.rst index 2046f1a59..f7b539c7a 100644 --- a/website/docs/index.rst +++ b/website/docs/index.rst @@ -6,6 +6,8 @@ PyPop User Guide .. only:: html + |guide_subtitle| + |htmlauthor| .. admonition:: *Documenting release* |version| *of PyPop*.