Fix and improve docs generation (#269)

* Fix and improve docs generation

* Fix and improve docs generation

.codespellignore

@@ -1,3 +1,5 @@
 uint
 master
 stdio
+alph
+ro

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="logo.svg" alt="CPP-Terminal logo"/>
+  <img src="docs/imgs/logo.svg" alt="CPP-Terminal logo"/>
 </p>
 
 [![Linux CI](https://github.com/jupyter-xeus/cpp-terminal/actions/workflows/linux.yml/badge.svg)](https://github.com/jupyter-xeus/cpp-terminal/actions/workflows/linux.yml)

docs/CMakeLists.txt

@@ -30,7 +30,23 @@ set(DOXYGEN_GENERATE_HTML YES)
 set(DOXYGEN_GENERATE_LATEX YES)
 set(DOXYGEN_COMPACT_LATEX YES)
 set(DOXYGEN_LATEX_BATCHMODE NO)
+set(DOXYGEN_PROJECT_LOGO "${CMAKE_CURRENT_SOURCE_DIR}/imgs/icon.png")
 set(DOXYGEN_IMAGE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/imgs")
+set(DOXYGEN_EXAMPLE_PATH "${PROJECT_SOURCE_DIR}/examples/")
+set(DOXYGEN_EXAMPLE_RECURSIVE YES)
+#set(DOXYGEN_LATEX_EXTRA_STYLESHEET "${CMAKE_CURRENT_SOURCE_DIR}/fixes.tex")
+if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/header.tex")
+  set(DOXYGEN_LATEX_HEADER "${CMAKE_CURRENT_SOURCE_DIR}/header.tex")
+endif ()
+if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/imgs/logo.png")
+  configure_file("${CMAKE_CURRENT_SOURCE_DIR}/imgs/logo.png" "${CMAKE_CURRENT_BINARY_DIR}/doxygen/latex/logo.png" COPYONLY)
+endif ()
+if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/footer.tex")
+  set(DOXYGEN_LATEX_FOOTER "${CMAKE_CURRENT_SOURCE_DIR}/footer.tex")
+endif ()
+if (EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/style.sty")
+  set(DOXYGEN_LATEX_EXTRA_STYLESHEET "${CMAKE_CURRENT_SOURCE_DIR}/style.sty")
+endif ()
 set(DOXYGEN_STRIP_FROM_PATH "/home/runner/work/${PROJECT_NAME}/${PROJECT_NAME};${PROJECT_SOURCE_DIR}")
 set(DOXYGEN_STRIP_FROM_INC_PATH "/home/runner/work/${PROJECT_NAME}/${PROJECT_NAME};${PROJECT_SOURCE_DIR}")
-doxyfile_docs(LUALATEX "${PROJECT_SOURCE_DIR}/cpp-terminal/" "${PROJECT_SOURCE_DIR}/examples/")
+doxyfile_docs("${PROJECT_SOURCE_DIR}/cpp-terminal/")

docs/header.tex

@@ -0,0 +1,271 @@
+% Latex header for doxygen 1.9.7
+% Handle batch mode
+$latex_batchmode
+
+% to overcome problems with too many open files
+\let\mypdfximage\pdfximage\def\pdfximage{\immediate\mypdfximage}
+
+\pdfminorversion=7
+
+% Set document class depending on configuration
+%%BEGIN COMPACT_LATEX
+\documentclass[twoside]{article}
+%%END COMPACT_LATEX
+%%BEGIN !COMPACT_LATEX
+\documentclass[twoside]{book}
+%%END !COMPACT_LATEX
+
+%% moved from doxygen.sty due to workaround for LaTex 2019 version and unmaintained tabu package
+\usepackage{ifthen}
+\ifx\requestedLaTeXdate\undefined
+\usepackage{array}
+\else
+\usepackage{array}[=2016-10-06]
+\fi
+%%
+\usepackage{pmboxdraw}
+% Packages required by doxygen
+\makeatletter
+\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
+% suppress package identification of infwarerr as it contains the word "warning"
+\let\@@protected@wlog\protected@wlog
+\def\protected@wlog#1{\wlog{package info suppressed}}
+\RequirePackage{infwarerr}
+\let\protected@wlog\@@protected@wlog
+\makeatother
+\IfFormatAtLeastTF{2016/01/01}{}{\usepackage{fixltx2e}} % for \textsubscript
+\IfFormatAtLeastTF{2015/01/01}{\pdfsuppresswarningpagegroup=1}{}
+
+\usepackage{doxygen}
+
+$extralatexstylesheet
+
+\usepackage{graphicx}
+\usepackage[utf8]{inputenc}
+\usepackage{makeidx}
+\PassOptionsToPackage{warn}{textcomp}
+\usepackage{textcomp}
+\usepackage[nointegrals]{wasysym}
+\usepackage{ifxetex}
+
+% NLS support packages
+$languagesupport
+
+% Define default fonts
+% Font selection
+%%BEGIN LATEX_FONTENC
+\usepackage[$latexfontenc]{fontenc}
+%%END LATEX_FONTENC
+
+% set main and monospaced font
+$latexfont
+
+\doxyallsectionsfont{%
+  \fontseries{bc}\selectfont%
+  \color{darkgray}%
+}
+\renewcommand{\DoxyLabelFont}{%
+  \fontseries{bc}\selectfont%
+  \color{darkgray}%
+}
+\newcommand{\+}{\discretionary{\mbox{\scriptsize$\hookleftarrow$}}{}{}}
+
+% Arguments of doxygenemoji:
+% 1) ':<text>:' form of the emoji, already LaTeX-escaped
+% 2) file with the name of the emoji without the .png extension
+% in case image exist use this otherwise use the ':<text>:' form
+\newcommand{\doxygenemoji}[2]{%
+\IfFileExists{$latexemojidirectory/#2.png}{\raisebox{-0.1em}{\includegraphics[height=0.9em]{$latexemojidirectory/#2.png}}}{#1}%
+}
+
+% Page & text layout
+\usepackage{geometry}
+\geometry{%
+$papertype,%
+top=2.5cm,%
+bottom=2.5cm,%
+left=2.5cm,%
+right=2.5cm%
+}
+\usepackage{changepage}
+
+% Allow a bit of overflow to go unnoticed by other means
+\tolerance=750
+\hfuzz=15pt
+\hbadness=750
+\setlength{\emergencystretch}{15pt}
+\setlength{\parindent}{0cm}
+\newcommand{\doxynormalparskip}{\setlength{\parskip}{3ex plus 2ex minus 2ex}}
+\newcommand{\doxytocparskip}{\setlength{\parskip}{1ex plus 0ex minus 0ex}}
+\doxynormalparskip
+% Redefine paragraph/subparagraph environments, using sectsty fonts
+\makeatletter
+\renewcommand{\paragraph}{%
+\@startsection{paragraph}{4}{0ex}{-1.0ex}{1.0ex}{%
+\normalfont\normalsize\bfseries\SS@parafont%
+}%
+}
+\renewcommand{\subparagraph}{%
+\@startsection{subparagraph}{5}{0ex}{-1.0ex}{1.0ex}{%
+\normalfont\normalsize\bfseries\SS@subparafont%
+}%
+}
+\makeatother
+
+\makeatletter
+\newcommand\hrulefilll{\leavevmode\leaders\hrule\hskip 0pt plus 1filll\kern\z@}
+\makeatother
+
+% Headers & footers
+\usepackage{fancyhdr}
+\pagestyle{fancyplain}
+\renewcommand{\footrulewidth}{0.4pt}
+
+\fancypagestyle{fancyplain}{
+\fancyhf{}
+\fancyhead[LE, RO]{\bfseries\thepage}
+\fancyhead[LO]{\bfseries\rightmark}
+\fancyhead[RE]{\bfseries\leftmark}
+\fancyfoot[LO, RE]{\bfseries\scriptsize $generatedby Doxygen }
+}
+
+\fancypagestyle{plain}{
+\fancyhf{}
+\fancyfoot[LO, RE]{\bfseries\scriptsize $generatedby Doxygen }
+\renewcommand{\headrulewidth}{0pt}
+}
+
+\pagestyle{fancyplain}
+
+
+%%BEGIN !COMPACT_LATEX
+\renewcommand{\chaptermark}[1]{%
+\markboth{#1}{}%
+}
+%%END !COMPACT_LATEX
+\renewcommand{\sectionmark}[1]{%
+\markright{\thesection\ #1}%
+}
+
+% ToC, LoF, LoT, bibliography, and index
+% Indices & bibliography
+\usepackage{natbib}
+\usepackage[titles]{tocloft}
+\setcounter{tocdepth}{3}
+\setcounter{secnumdepth}{5}
+
+% creating indexes
+$makeindex
+
+$extralatexpackages
+
+$latexspecialformulachars
+
+%%BEGIN FORMULA_MACROFILE
+\input{$formulamacrofile}
+%%END FORMULA_MACROFILE
+
+% Hyperlinks
+%%BEGIN PDF_HYPERLINKS
+% Hyperlinks (required, but should be loaded last)
+\ifpdf
+\usepackage[pdftex,pagebackref=true]{hyperref}
+\else
+\ifxetex
+\usepackage[pagebackref=true]{hyperref}
+\else
+\usepackage[ps2pdf,pagebackref=true]{hyperref}
+\fi
+\fi
+
+\hypersetup{%
+colorlinks=true,%
+linkcolor=blue,%
+citecolor=blue,%
+unicode,%
+pdftitle={$projectname},%
+pdfsubject={$projectbrief}%
+}
+
+%%END PDF_HYPERLINKS
+
+% Custom commands used by the header
+% Custom commands
+\newcommand{\clearemptydoublepage}{%
+\newpage{\pagestyle{empty}\cleardoublepage}%
+}
+
+% caption style definition
+\usepackage{caption}
+\captionsetup{labelsep=space,justification=centering,font={bf},singlelinecheck=off,skip=4pt,position=top}
+
+
+% in page table of contents
+\IfFormatAtLeastTF{2023/05/01}{\usepackage[deeplevels]{etoc}}{\usepackage[deeplevels]{etoc_doxygen}}
+\etocsettocstyle{\doxytocparskip}{\doxynormalparskip}
+\etocsetlevel{subsubsubsection}{4}
+\etocsetlevel{subsubsubsubsection}{5}
+\etocsetlevel{subsubsubsubsubsection}{6}
+\etocsetlevel{subsubsubsubsubsubsection}{7}
+\etocsetlevel{paragraph}{8}
+\etocsetlevel{subparagraph}{9}
+
+% prevent numbers overlap the titles in toc
+\renewcommand{\numberline}[1]{#1~}
+
+% End of preamble, now comes the document contents
+%===== C O N T E N T S =====
+
+\begin{document}
+\raggedbottom
+
+$latexdocumentpre
+
+% Titlepage & ToC
+%%BEGIN PDF_HYPERLINKS
+%%BEGIN USE_PDFLATEX
+% To avoid duplicate page anchors due to reuse of same numbers for
+% the index (be it as roman numbers)
+\hypersetup{pageanchor=false,
+bookmarksnumbered=true,
+pdfencoding=unicode
+}
+%%END USE_PDFLATEX
+%%END PDF_HYPERLINKS
+\pagenumbering{alph}
+\begin{titlepage}
+\vspace*{7cm}
+\begin{center}%
+\includegraphics[width=0.8\textwidth]{logo.png}\\
+%{\Large $title}\\
+%%BEGIN PROJECT_NUMBER
+[1ex]\large $projectnumber \\
+%%END PROJECT_NUMBER
+\vspace*{1cm}
+{\large $generatedby Doxygen $doxygenversion}\\
+%%BEGIN LATEX_TIMESTAMP
+\vspace*{0.5cm}
+{\small $datetime}
+%%END LATEX_TIMESTAMP
+\end{center}
+\end{titlepage}
+
+%%BEGIN !COMPACT_LATEX
+\clearemptydoublepage
+%%END !COMPACT_LATEX
+\pagenumbering{roman}
+
+\tableofcontents
+%%BEGIN !COMPACT_LATEX
+\clearemptydoublepage
+%%END !COMPACT_LATEX
+\pagenumbering{arabic}
+
+%%BEGIN PDF_HYPERLINKS
+%%BEGIN USE_PDFLATEX
+% re-enable anchors again
+\hypersetup{pageanchor=true}
+%%END USE_PDFLATEX
+%%END PDF_HYPERLINKS
+
+%--- Begin generated contents ---