Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Latex generation improvements #18141

Merged
merged 3 commits into from
Jun 1, 2021
Merged

docs: Latex generation improvements #18141

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
eaba4eb
docs: improve Latex generation
a-mr May 26, 2021
18ffc2d
make it work on Windows + fix ] escaping
a-mr May 27, 2021
41adb80
minor fixes with escapes and style
a-mr May 31, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion compiler/docgen.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -549,7 +549,7 @@ proc getAllRunnableExamplesImpl(d: PDoc; n: PNode, dest: var string,
var msg = "Example:"
if rdoccmd.len > 0: msg.add " cmd: " & rdoccmd
dispA(d.conf, dest, "\n<p><strong class=\"examples_text\">$1</strong></p>\n",
"\n\\textbf{$1}\n", [msg])
"\n\n\\textbf{$1}\n", [msg])
inc d.listingCounter
let id = $d.listingCounter
dest.add(d.config.getOrDefault"doc.listing_start" % [id, "langNim", ""])
Expand Down
202 changes: 146 additions & 56 deletions config/nimdoc.tex.cfg
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ split.item.toc = "20"
# after this number of characters

doc.section = """
\rsthA{$sectionTitle}\label{$sectionID}
\rsthA[$sectionTitle]{$sectionTitle}\label{$sectionID}

$content
"""

Expand All @@ -17,12 +18,16 @@ doc.section.toc = ""

doc.item = """

\vspace{1em}
\phantomsection\addcontentsline{toc}{subsection}{$uniqueName}

\begin{rstpre}
\begin{rstdocitem}
$header
\end{rstpre}
\end{rstdocitem}

\begin{addmargin}[0.05\linewidth]{0pt}
$desc
\end{addmargin}
"""

doc.item.toc = ""
Expand All @@ -42,46 +47,118 @@ $content

# $1 - number of listing in document, $2 - language (e.g. langNim), $3 - anchor
doc.listing_start = "\\begin{rstpre}\n"
doc.listing_end = "\n\\end{rstpre}\n"
doc.listing_end = "\n\\end{rstpre}\n\n"

doc.file = """
% This file was generated by Nim.
% Generated: $date $time UTC
\documentclass[a4paper]{article}
\usepackage[left=2cm,right=3cm,top=3cm,bottom=3cm]{geometry}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
%
% Compile it by: xelatex (up to 3 times to get labels generated)
% -------
%
\documentclass[a4paper,11pt]{article}
\usepackage[a4paper,xetex,left=3cm,right=3cm,top=1.5cm,bottom=2cm]{geometry}

% for 2-sided printing with larger inner "binding" margin
%\usepackage[a4paper,xetex,twoside,left=4cm,right=2cm,top=1.5cm,bottom=2cm]{geometry}
% for e-readers with 1.77:1 aspect ratio (e.g. 1920x1080)
%\usepackage[xetex,paperheight=27.6cm,paperwidth=15.5cm,left=3mm,right=3mm,top=3mm,bottom=3mm]{geometry}
% for e-readers with 1.45:1 aspect ratio (e.g. 1200x825)
%\usepackage[xetex,paperheight=22.5cm,paperwidth=15.5cm,left=3mm,right=3mm,top=3mm,bottom=3mm]{geometry}
% for e-readers with 1.33:1 aspect ratio (e.g. 1872x1404)
%\usepackage[xetex,paperheight=20.7cm,paperwidth=15.5cm,left=3mm,right=3mm,top=3mm,bottom=3mm]{geometry}

\usepackage{fontspec}
% logic to select default font with some fall-back fonts.
\IfFontExistsTF{Times New Roman}{%
\setmainfont{Times New Roman} % the default font
\typeout{========================================= nim: using Times New Roman}
}{
\IfFontExistsTF{FreeSerif}{%
\setmainfont{FreeSerif} % fallback #1 - official GNU font, resembles Times
\typeout{========================================= nim: using FreeSerif}
}{
\IfFontExistsTF{DejaVuSerif}{%
\setmainfont{DejaVuSerif} % fallback #2 - very widespread free font
\typeout{========================================= nim: using DejaVuSerif}
}{
\typeout{!!!!!!!!!!!!!!!!!!! Fonts not found !!!!!!!!!!!!!!!!!!!!!!!}
}
}
}

% default monospace font for code:
\usepackage{GoMono}
\usepackage{relsize}
% make this monospace font 2 steps smaller to hold 80-character line
\newcommand{\rstverbblockfont}{\smaller[2]}
\newcommand{\rstverbinlinefont}{\smaller}

\usepackage{parskip} % paragraphs delimited by vertical space, no indent
\usepackage{graphicx}
\usepackage{lmodern}
\usepackage{fancyvrb, courier}
\usepackage{tabularx}
\usepackage{hyperref}
\usepackage{enumitem} % for option list, enumList, and rstfootnote

\usepackage{dingbat} % for \carriagereturn, etc
\usepackage{fvextra} % for code blocks (works better than original fancyvrb)
\fvset{
breaklines,
breakafter={=}:|\_\{\}[](){,}.;+-*/'",
breaksymbolleft=\color{red}{\ensuremath{\hookrightarrow}},
breaksymbolright=\color{red}{\small\carriagereturn}
}
\fvinlineset{%
breaklines,
breakafter={=}:|\_\{\}[](){,}.;+-*/'",
% that does not work at all when we underline inline code by ulem :-(
commandchars=\\\{\}
}

\usepackage{scrextend} % for the `addmargin` environment

\usepackage{xcolor}
\usepackage[tikz]{mdframed}
\usetikzlibrary{shadows}
\mdfsetup{%
linewidth=3,
topline=false,
rightline=false,
bottomline=false}
\usepackage[urlbordercolor=blue,linkbordercolor=cyan,
pdfborderstyle={/S/U/W 1}]{hyperref}
\usepackage{enumitem} % for option list, enumList, and rstfootnote

\begin{document}
\title{$title $version $subtitle}
\author{$author}
\usepackage[most]{tcolorbox} % boxes around admonitions, code blocks, doc.item

\tolerance 1414
\hbadness 1414
\emergencystretch 1.5em
\hfuzz 0.3pt
\widowpenalty=10000
\vfuzz \hfuzz
\raggedbottom
\newtcolorbox{rstadmonition}[1][]{blanker, breakable,
left=3mm, right=3mm, top=1mm, bottom=1mm,
before upper=\indent, parbox=false, #1}

\definecolor{rstframecolor}{rgb}{0.85, 0.8, 0.6}

\newtcolorbox{rstprebox}[1][]{blanker, breakable,
left=3mm, right=3mm, top=1mm, bottom=1mm,
borderline ={0.1em}{0pt}{rstframecolor},
before upper=\indent, parbox=false, #1}

\newenvironment{rstpre}{%
\VerbatimEnvironment\begingroup\begin{rstprebox}%
\begin{Verbatim}[fontsize=\rstverbblockfont , commandchars=\\\{\}]}%
{\end{Verbatim}\end{rstprebox}\endgroup}

\newtcolorbox{rstdocitembox}[1][]{blanker, breakable,
left=3mm, right=3mm, top=1mm, bottom=1mm,
borderline ={1pt}{0pt}{cyan},
before upper=\indent, parbox=false, #1}

% Inline code formatting: grey underline,
% use \Verb from fvextras e.g. to display -- correctly as double -
\usepackage[normalem]{ulem}
\newcommand\rstuline{\bgroup\markoverwith{\textcolor{rstframecolor}{\rule[-0.8ex]{2pt}{1.0pt}}}\ULon}

\newcommand{\rstcode}[1]{%
{\rstverbinlinefont\Verb{\rstuline{#1}}}%
}

\newcommand{\rstcodeitem}[1]{\Verb{#1}}

\newenvironment{rstdocitem}{%
\VerbatimEnvironment\begingroup\begin{rstdocitembox}%
\begin{Verbatim}[fontsize=\rstverbblockfont , commandchars=\\\{\}]}%
{\end{Verbatim}\end{rstdocitembox}\endgroup}

\maketitle

\newenvironment{rstpre}{\VerbatimEnvironment\begingroup\begin{Verbatim}[fontsize=\footnotesize , commandchars=\\\{\}]}{\end{Verbatim}\endgroup}
\newenvironment{rstfootnote}{\begin{description}[labelindent=1em,leftmargin=1em,labelwidth=2.6em]}{\end{description}}
\ifdim\linewidth<30em
\def\rstoptleftmargin{0.4\linewidth}
Expand All @@ -93,37 +170,41 @@ bottomline=false}
\newenvironment{rstoptlist}{%
\begin{description}[font=\sffamily\bfseries,style=nextline,leftmargin=\rstoptleftmargin,labelwidth=\rstoptlabelwidth]}{\end{description}}

% to pack tabularx into a new environment, special syntax is needed :-(
\newenvironment{rsttab}[1]{\tabularx{\linewidth}{#1}}{\endtabularx}
\usepackage{tabulary} % tables with adjustable cell width and no overflow
% make tabulary prevent overflows (https://tex.stackexchange.com/a/195088)
\tymin=60pt
\tymax=\maxdimen
% to pack tabulary into a new environment, special syntax is needed :-(
\newenvironment{rsttab}[1]{\tabulary{\linewidth}{#1}}{\endtabulary}

\newcommand{\rstsub}[1]{\raisebox{-0.5ex}{\scriptsize{#1}}}
\newcommand{\rstsup}[1]{\raisebox{0.5ex}{\scriptsize{#1}}}

\newcommand{\rsthA}[1]{\section{#1}}
\newcommand{\rsthB}[1]{\subsection{#1}}
\newcommand{\rsthC}[1]{\subsubsection{#1}}
\newcommand{\rsthD}[1]{\paragraph{#1}}
\newcommand{\rsthE}[1]{\paragraph{#1}}
\newcommand{\rsthA}[2][]{\section[#1]{#2}}
\newcommand{\rsthB}[2][]{\subsection[#1]{#2}}
\newcommand{\rsthC}[2][]{\subsubsection[#1]{#2}}
\newcommand{\rsthD}[2][]{\paragraph[#1]{#2}}
\newcommand{\rsthE}[2][]{\paragraph[#1]{#2}}

\newcommand{\rstovA}[1]{\section*{#1}}
\newcommand{\rstovB}[1]{\subsection*{#1}}
\newcommand{\rstovC}[1]{\subsubsection*{#1}}
\newcommand{\rstovD}[1]{\paragraph*{#1}}
\newcommand{\rstovE}[1]{\paragraph*{#1}}
\newcommand{\rstovA}[2][]{\section*[#1]{#2}}
\newcommand{\rstovB}[2][]{\subsection*[#1]{#2}}
\newcommand{\rstovC}[2][]{\subsubsection*[#1]{#2}}
\newcommand{\rstovD}[2][]{\paragraph*[#1]{#2}}
\newcommand{\rstovE}[2][]{\paragraph*[#1]{#2}}

% Syntax highlighting:
\newcommand{\spanDecNumber}[1]{#1}
\newcommand{\spanBinNumber}[1]{#1}
\newcommand{\spanHexNumber}[1]{#1}
\newcommand{\spanOctNumber}[1]{#1}
\newcommand{\spanFloatNumber}[1]{#1}
\newcommand{\spanDecNumber}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanBinNumber}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanHexNumber}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanOctNumber}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanFloatNumber}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanIdentifier}[1]{#1}
\newcommand{\spanKeyword}[1]{\textbf{#1}}
\newcommand{\spanStringLit}[1]{#1}
\newcommand{\spanLongStringLit}[1]{#1}
\newcommand{\spanStringLit}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanLongStringLit}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanCharLit}[1]{#1}
\newcommand{\spanEscapeSequence}[1]{#1}
\newcommand{\spanOperator}[1]{#1}
\newcommand{\spanOperator}[1]{\textbf{#1}}
\newcommand{\spanPunctuation}[1]{#1}
\newcommand{\spanComment}[1]{\emph{#1}}
\newcommand{\spanLongComment}[1]{\emph{#1}}
Expand All @@ -132,7 +213,7 @@ bottomline=false}
\newcommand{\spanTagEnd}[1]{#1}
\newcommand{\spanKey}[1]{#1}
\newcommand{\spanValue}[1]{#1}
\newcommand{\spanRawData}[1]{#1}
\newcommand{\spanRawData}[1]{\textbf{\textcolor{darkgray}{#1}}}
\newcommand{\spanAssembler}[1]{#1}
\newcommand{\spanPreprocessor}[1]{#1}
\newcommand{\spanDirective}[1]{#1}
Expand All @@ -142,11 +223,20 @@ bottomline=false}
\newcommand{\spanLabel}[1]{#1}
\newcommand{\spanReference}[1]{#1}
\newcommand{\spanOther}[1]{#1}
\newcommand{\spantok}[1]{\frame{#1}}
\newcommand{\spantok}[1]{\fbox{#1}}
\newcommand{\spanPrompt}[1]{\textcolor{red}{\textbf{#1}}}
\newcommand{\spanProgramOutput}[1]{\textcolor{gray}{\textbf{#1}}}
\newcommand{\spanProgramOutput}[1]{\textcolor{darkgray}{\textbf{#1}}}
\newcommand{\spanprogram}[1]{\textbf{\underline{#1}}}
\newcommand{\spanoption}[1]{\textbf{#1}}
\newcommand{\spanoption}[1]{\textbf{\textcolor{darkgray}{#1}}}

\begin{document}
\title{$title $version $subtitle}
\author{$author}

% Never allow text overflow to margin:
\setlength\emergencystretch{\hsize}\hbadness=10000

\maketitle

$content
\end{document}
Expand Down
18 changes: 17 additions & 1 deletion lib/packages/docutils/rstast.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,8 +349,24 @@ proc renderRstToJson*(node: PRstNode): string =
## }
renderRstToJsonNode(node).pretty

proc renderRstToText*(node: PRstNode): string =
## minimal text representation of markup node
const code = {rnCodeFragment, rnInterpretedText, rnInlineLiteral, rnInlineCode}
if node == nil:
return ""
case node.kind
of rnLeaf, rnSmiley:
result.add node.text
else:
if node.kind in code: result.add "`"
for i in 0 ..< node.sons.len:
if node.kind in {rnInlineCode, rnCodeBlock} and i == 0:
continue # omit language specifier
result.add renderRstToText(node.sons[i])
if node.kind in code: result.add "`"

proc renderRstToStr*(node: PRstNode, indent=0): string =
## Writes the parsed RST `node` into a compact string
## Writes the parsed RST `node` into an AST tree with compact string
## representation in the format (one line per every sub-node):
## ``indent - kind - [text|level|order|adType] - anchor (if non-zero)``
## (suitable for debugging of RST parsing).
Expand Down
Loading