diff --git a/.sphinx/_static/custom.css b/.sphinx/_static/custom.css index 3ceeb188..2b9e81fb 100644 --- a/.sphinx/_static/custom.css +++ b/.sphinx/_static/custom.css @@ -376,3 +376,17 @@ p code.literal { .highlight .o { color: #BB5400; } + +.rubric > .hclass2 { + display: block; + font-size: 2em; + border-radius: .5rem; + font-weight: 300; + line-height: 1.25; + margin-top: 1.75rem; + margin-right: -0.5rem; + margin-bottom: 0.5rem; + margin-left: -0.5rem; + padding-left: .5rem; + padding-right: .5rem; +} \ No newline at end of file diff --git a/.sphinx/fonts/Ubuntu-B.ttf b/.sphinx/fonts/Ubuntu-B.ttf new file mode 100644 index 00000000..b173da27 Binary files /dev/null and b/.sphinx/fonts/Ubuntu-B.ttf differ diff --git a/.sphinx/fonts/Ubuntu-R.ttf b/.sphinx/fonts/Ubuntu-R.ttf new file mode 100644 index 00000000..d748728a Binary files /dev/null and b/.sphinx/fonts/Ubuntu-R.ttf differ diff --git a/.sphinx/fonts/Ubuntu-RI.ttf b/.sphinx/fonts/Ubuntu-RI.ttf new file mode 100644 index 00000000..4f2d2bc7 Binary files /dev/null and b/.sphinx/fonts/Ubuntu-RI.ttf differ diff --git a/.sphinx/fonts/UbuntuMono-B.ttf b/.sphinx/fonts/UbuntuMono-B.ttf new file mode 100644 index 00000000..7bd66657 Binary files /dev/null and b/.sphinx/fonts/UbuntuMono-B.ttf differ diff --git a/.sphinx/fonts/UbuntuMono-R.ttf b/.sphinx/fonts/UbuntuMono-R.ttf new file mode 100644 index 00000000..fdd309d7 Binary files /dev/null and b/.sphinx/fonts/UbuntuMono-R.ttf differ diff --git a/.sphinx/fonts/UbuntuMono-RI.ttf b/.sphinx/fonts/UbuntuMono-RI.ttf new file mode 100644 index 00000000..18f81a29 Binary files /dev/null and b/.sphinx/fonts/UbuntuMono-RI.ttf differ diff --git a/.sphinx/fonts/ubuntu-font-licence-1.0.txt b/.sphinx/fonts/ubuntu-font-licence-1.0.txt new file mode 100644 index 00000000..ae78a8f9 --- /dev/null +++ b/.sphinx/fonts/ubuntu-font-licence-1.0.txt @@ -0,0 +1,96 @@ +------------------------------- +UBUNTU FONT LICENCE Version 1.0 +------------------------------- + +PREAMBLE +This licence allows the licensed fonts to be used, studied, modified and +redistributed freely. The fonts, including any derivative works, can be +bundled, embedded, and redistributed provided the terms of this licence +are met. The fonts and derivatives, however, cannot be released under +any other licence. The requirement for fonts to remain under this +licence does not require any document created using the fonts or their +derivatives to be published under this licence, as long as the primary +purpose of the document is not to be a vehicle for the distribution of +the fonts. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this licence and clearly marked as such. This may +include source files, build scripts and documentation. + +"Original Version" refers to the collection of Font Software components +as received under this licence. + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to +a new environment. + +"Copyright Holder(s)" refers to all individuals and companies who have a +copyright ownership of the Font Software. + +"Substantially Changed" refers to Modified Versions which can be easily +identified as dissimilar to the Font Software by users of the Font +Software comparing the Original Version with the Modified Version. + +To "Propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification and with or without charging +a redistribution fee), making available to the public, and in some +countries other activities as well. + +PERMISSION & CONDITIONS +This licence does not grant any rights under trademark law and all such +rights are reserved. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of the Font Software, to propagate the Font Software, subject to +the below conditions: + +1) Each copy of the Font Software must contain the above copyright +notice and this licence. These can be included either as stand-alone +text files, human-readable headers or in the appropriate machine- +readable metadata fields within text or binary files as long as those +fields can be easily viewed by the user. + +2) The font name complies with the following: +(a) The Original Version must retain its name, unmodified. +(b) Modified Versions which are Substantially Changed must be renamed to +avoid use of the name of the Original Version or similar names entirely. +(c) Modified Versions which are not Substantially Changed must be +renamed to both (i) retain the name of the Original Version and (ii) add +additional naming elements to distinguish the Modified Version from the +Original Version. The name of such Modified Versions must be the name of +the Original Version, with "derivative X" where X represents the name of +the new work, appended to that name. + +3) The name(s) of the Copyright Holder(s) and any contributor to the +Font Software shall not be used to promote, endorse or advertise any +Modified Version, except (i) as required by this licence, (ii) to +acknowledge the contribution(s) of the Copyright Holder(s) or (iii) with +their explicit written permission. + +4) The Font Software, modified or unmodified, in part or in whole, must +be distributed entirely under this licence, and must not be distributed +under any other licence. The requirement for fonts to remain under this +licence does not affect any document created using the Font Software, +except any version of the Font Software extracted from a document +created using the Font Software may only be distributed under this +licence. + +TERMINATION +This licence becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF +COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER +DEALINGS IN THE FONT SOFTWARE. diff --git a/.sphinx/images/Canonical-logo-4x.png b/.sphinx/images/Canonical-logo-4x.png new file mode 100644 index 00000000..fd75696e Binary files /dev/null and b/.sphinx/images/Canonical-logo-4x.png differ diff --git a/.sphinx/images/front-page-light.pdf b/.sphinx/images/front-page-light.pdf new file mode 100644 index 00000000..bb68cdf8 Binary files /dev/null and b/.sphinx/images/front-page-light.pdf differ diff --git a/.sphinx/images/front-page.png b/.sphinx/images/front-page.png new file mode 100644 index 00000000..c80e8430 Binary files /dev/null and b/.sphinx/images/front-page.png differ diff --git a/.sphinx/images/normal-page-footer.pdf b/.sphinx/images/normal-page-footer.pdf new file mode 100644 index 00000000..dfd73cbc Binary files /dev/null and b/.sphinx/images/normal-page-footer.pdf differ diff --git a/.sphinx/latex_elements_template.txt b/.sphinx/latex_elements_template.txt new file mode 100644 index 00000000..2b13b514 --- /dev/null +++ b/.sphinx/latex_elements_template.txt @@ -0,0 +1,119 @@ +{ + 'papersize': 'a4paper', + 'pointsize': '11pt', + 'fncychap': '', + 'preamble': r''' +%\usepackage{charter} +%\usepackage[defaultsans]{lato} +%\usepackage{inconsolata} +\setmainfont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{Ubuntu} +\setmonofont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{UbuntuMono} +\usepackage[most]{tcolorbox} +\tcbuselibrary{breakable} +\usepackage{lastpage} +\usepackage{tabto} +\usepackage{ifthen} +\usepackage{etoolbox} +\usepackage{fancyhdr} +\usepackage{graphicx} +\usepackage{titlesec} +\usepackage{fontspec} +\usepackage{tikz} +\usepackage{changepage} +\usepackage{array} +\usepackage{tabularx} +\definecolor{yellowgreen}{RGB}{154, 205, 50} +\definecolor{title}{RGB}{76, 17, 48} +\definecolor{subtitle}{RGB}{116, 27, 71} +\definecolor{label}{RGB}{119, 41, 100} +\definecolor{copyright}{RGB}{174, 167, 159} +\makeatletter +\def\tcb@finalize@environment{% + \color{.}% hack for xelatex + \tcb@layer@dec% +} +\makeatother +\newenvironment{sphinxclassprompt}{\color{yellowgreen}\setmonofont[Color = 9ACD32, UprightFont = *-R, Extension = .ttf]{UbuntuMono}}{} +\tcbset{enhanced jigsaw, colback=black, fontupper=\color{white}} +\newtcolorbox{termbox}{use color stack, breakable, colupper=white, halign=flush left} +\newenvironment{sphinxclassterminal}{\setmonofont[Color = white, UprightFont = *-R, Extension = .ttf]{UbuntuMono}\sphinxsetup{VerbatimColor={black}}\begin{termbox}}{\end{termbox}} +\newcommand{\dimtorightedge}{% + \dimexpr\paperwidth-1in-\hoffset-\oddsidemargin\relax} +\newcommand{\dimtotop}{% + \dimexpr\height-1in-\voffset-\topmargin-\headheight-\headsep\relax} +\newtoggle{tpage} +\AtBeginEnvironment{titlepage}{\global\toggletrue{tpage}} +\fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[R]{\thepage\ of \pageref*{LastPage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0pt} +} +\fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[R]{\thepage\ of \pageref*{LastPage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0pt} +} +\fancypagestyle{titlepage}{% + \fancyhf{} + \fancyfoot[L]{\footnotesize \textcolor{copyright}{© 2024 Canonical Ltd. All rights reserved.}} +} +\newcommand\sphinxbackoftitlepage{\thispagestyle{titlepage}} +\titleformat{\chapter}[block]{\Huge \color{title} \bfseries\filright}{\thechapter .}{1.5ex}{} +\titlespacing{\chapter}{0pt}{0pt}{0pt} +\titleformat{\section}[block]{\huge \bfseries\filright}{\thesection .}{1.5ex}{} +\titlespacing{\section}{0pt}{0pt}{0pt} +\titleformat{\subsection}[block]{\Large \bfseries\filright}{\thesubsection .}{1.5ex}{} +\titlespacing{\subsection}{0pt}{0pt}{0pt} +\setcounter{tocdepth}{1} +\renewcommand\pagenumbering[1]{} +''', + 'sphinxsetup': 'verbatimwithframe=false, pre_border-radius=0pt, verbatimvisiblespace=\\phantom{}, verbatimcontinued=\\phantom{}', + 'extraclassoptions': 'openany,oneside', + 'maketitle': r''' +\begin{titlepage} +\begin{flushleft} + \begin{tikzpicture}[remember picture,overlay] + \node[anchor=south east, inner sep=0] at (current page.south east) { + \includegraphics[width=\paperwidth, height=\paperheight]{front-page-light} + }; + \end{tikzpicture} +\end{flushleft} + +\vspace*{3cm} + +\begin{adjustwidth}{8cm}{0pt} +\begin{flushleft} + \huge \textcolor{black}{\textbf{}{\raggedright{$PROJECT}}} +\end{flushleft} +\end{adjustwidth} + +\vfill + +\begin{adjustwidth}{8cm}{0pt} +\begin{tabularx}{0.5\textwidth}{ l l } + \textcolor{lightgray}{© 2024 Canonical Ltd.} & \hspace{3cm} \\ + \textcolor{lightgray}{All rights reserved.} & \hspace{3cm} \\ + & \hspace{3cm} \\ + & \hspace{3cm} \\ + +\end{tabularx} +\end{adjustwidth} + +\end{titlepage} +\RemoveFromHook{shipout/background} +\AddToHook{shipout/background}{ + \begin{tikzpicture}[remember picture,overlay] + \node[anchor=south west, align=left, inner sep=0] at (current page.south west) { + \includegraphics[width=\paperwidth]{normal-page-footer} + }; + \end{tikzpicture} + \begin{tikzpicture}[remember picture,overlay] + \node[anchor=north east, opacity=0.5, inner sep=35] at (current page.north east) { + \includegraphics[width=4cm]{Canonical-logo-4x} + }; + \end{tikzpicture} + } +''', +} \ No newline at end of file diff --git a/Makefile.sp b/Makefile.sp index d4040597..f5a1be7b 100644 --- a/Makefile.sp +++ b/Makefile.sp @@ -17,10 +17,11 @@ VENV = $(VENVDIR)/bin/activate TARGET = * ALLFILES = *.rst **/*.rst ADDPREREQS ?= +REQPDFPACKS = latexmk fonts-freefont-otf texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended texlive-font-utils texlive-lang-cjk texlive-xetex plantuml xindy tex-gyre dvipng .PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \ sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \ - sp-pa11y Makefile.sp sp-vale + sp-pa11y sp-pdf-prep-force sp-pdf-prep sp-pdf Makefile.sp sp-vale sp-full-help: $(VENVDIR) @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) @@ -114,7 +115,25 @@ sp-vale: sp-install @echo "" @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET) - +sp-pdf-prep: sp-install + @for packageName in $(REQPDFPACKS); do (dpkg-query -W -f='$${Status}' $$packageName 2>/dev/null | \ + grep -c "ok installed" >/dev/null && echo "Package $$packageName is installed") && continue || \ + (echo "\nPDF generation requires the installation of the following packages: $(REQPDFPACKS)" && \ + echo "" && echo "Run sudo make pdf-prep-force to install these packages" && echo "" && echo \ + "Please be aware these packages will be installed to your system") && exit 1 ; done + +sp-pdf-prep-force: + apt-get update + apt-get upgrade -y + apt-get install --no-install-recommends -y $(REQPDFPACKS) \ + +sp-pdf: sp-pdf-prep + @. $(VENV); sphinx-build -M latexpdf "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + @rm ./$(BUILDDIR)/latex/front-page-light.pdf || true + @rm ./$(BUILDDIR)/latex/normal-page-footer.pdf || true + @find ./$(BUILDDIR)/latex -name "*.pdf" -exec mv -t ./$(BUILDDIR) {} + + @rm -r $(BUILDDIR)/latex + @echo "\nOutput can be found in ./$(BUILDDIR)\n" # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/conf.py b/conf.py index e0c23fdd..3c431851 100644 --- a/conf.py +++ b/conf.py @@ -4,6 +4,7 @@ from urllib.parse import urlparse from git import Repo, InvalidGitRepositoryError import time +import ast sys.path.append('./') from custom_conf import * @@ -210,4 +211,28 @@ def get_contributors_for_file(github_url, github_folder, pagename, page_source_s return sorted_contributors_list html_context['get_contribs'] = get_contributors_for_file -############################################################# + +############################################################ +### PDF configuration +############################################################ + +latex_additional_files = [ + "./.sphinx/fonts/Ubuntu-B.ttf", + "./.sphinx/fonts/Ubuntu-R.ttf", + "./.sphinx/fonts/Ubuntu-RI.ttf", + "./.sphinx/fonts/UbuntuMono-R.ttf", + "./.sphinx/fonts/UbuntuMono-RI.ttf", + "./.sphinx/fonts/UbuntuMono-B.ttf", + "./.sphinx/images/Canonical-logo-4x.png", + "./.sphinx/images/front-page-light.pdf", + "./.sphinx/images/normal-page-footer.pdf", +] + +latex_engine = 'xelatex' +latex_show_pagerefs = True +latex_show_urls = 'footnote' + +with open(".sphinx/latex_elements_template.txt", "rt") as file: + latex_config = file.read() + +latex_elements = ast.literal_eval(latex_config.replace("$PROJECT", project)) \ No newline at end of file diff --git a/custom_conf.py b/custom_conf.py index 4ad87f4e..edd8e951 100644 --- a/custom_conf.py +++ b/custom_conf.py @@ -222,4 +222,6 @@ rst_prolog = ''' .. role:: center :class: align-center +.. role:: h2 + :class: hclass2 ''' diff --git a/doc-cheat-sheet.rst b/doc-cheat-sheet.rst index ca3fd062..0999c459 100644 --- a/doc-cheat-sheet.rst +++ b/doc-cheat-sheet.rst @@ -19,6 +19,8 @@ Also see the `Sphinx reStructuredText Primer