From 1e30157faac7a8dbe599bd4210f6ca986be0ae45 Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Mon, 7 Aug 2023 08:41:32 +0200 Subject: [PATCH 01/33] Make better use of make itself --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index b4a12907a..bb843a4d5 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ SHELL := /bin/bash # this pattern rule lets you run "make build" (or any other target # in docs/Makefile) in this directory as though you were in docs/ %: - cd docs && make $@ + $(MAKE) -C docs $@ clean-build: rm -rf docs/_build From e4457afcdc51824b2e0dc36eb0584d3c2f2a9f26 Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Mon, 7 Aug 2023 08:45:16 +0200 Subject: [PATCH 02/33] Turn on nit-picky mode, warn about all missing references --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index be92bfa43..36aab7406 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = -W -T -v +SPHINXOPTS = -W -T -v -n SPHINXBUILD = python -m sphinx PAPER = BUILDDIR = _build From d8164401eb74a6da650ca95751621ca021bea1ff Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Mon, 7 Aug 2023 19:01:39 +0200 Subject: [PATCH 03/33] Factor LaTeX logic out of conf.py (some more) This should make things easier to graps and also to customize. --- docs/conf.py | 161 ++++------------------------------ docs/latex/preamble_end.sty | 115 ++++++++++++++++++++++++ docs/latex/preamble_start.sty | 1 + docs/latex/titlepage.sty | 17 ++++ 4 files changed, 149 insertions(+), 145 deletions(-) create mode 100644 docs/latex/preamble_end.sty create mode 100644 docs/latex/preamble_start.sty create mode 100644 docs/latex/titlepage.sty diff --git a/docs/conf.py b/docs/conf.py index 94a33b4b5..6cd1e2b8c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -206,6 +206,7 @@ # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] +# this is now (largely?) unused and replaced by the {dl|git|gitannex}cmd roles manpages_url = 'https://docs.datalad.org/generated/man/{page}.html' # numbered figures for better referencing @@ -325,8 +326,8 @@ ( 'book_main', 'dataladhandbook.tex', - u'The DataLad Handbook', - u'', + 'The DataLad Handbook', + '', 'manual'), ] @@ -339,6 +340,11 @@ '../artwork/more_boxicon.pdf', '../artwork/more_boxicon_inline.pdf', '../artwork/win_boxicon.pdf', + # the following files are included in the main latex document + # in the order with which the are listed here + 'latex/preamble_start.sty', + 'latex/preamble_end.sty', + 'latex/titlepage.sty', ] latex_toplevel_sectioning = 'part' @@ -363,153 +369,18 @@ cautionBorderColor={named}{Cyan},% cautionBgColor={named}{LightCyan}% """, - 'maketitle': r""" -\begin{titlepage} -\raggedleft -\rule{1pt}{\textheight} -\hspace{0.05\textwidth} -\parbox[b]{0.75\textwidth}{ -\hfill{\footnotesize %s}\\[1\baselineskip] -\includegraphics[width=0.75\textwidth]{logo.pdf}\\ -{\Huge\textbf{Handbook}}\\ -{\Large Introduction \textbullet\ Advanced topics \textbullet\ Use cases}\\[2\baselineskip] -{\Large\textsc{Adina~Wagner \& Michael~Hanke}\\[1\baselineskip] -{\small \textit{with}}\\[1\baselineskip] -{ -\raggedright -%s\\ -}} -} -\end{titlepage} -""" % ( - release, - ', '.join('\\mbox{%s}' % a for a in authors[1:-1]), - ), 'extraclassoptions': 'openany,twoside', + 'passoptionstopackages': r'\input{preamble_start.sty}', 'fncychap': r'\usepackage[Bjarne]{fncychap}', - 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', - 'preamble': r""" -\usepackage[labelfont=bf,singlelinecheck=false]{caption} -\renewcommand{\sphinxstyletheadfamily}{\bfseries} -\usepackage{charter} -\usepackage[defaultsans]{lato} -\usepackage{inconsolata} -\usepackage[hang,flushmargin,multiple]{footmisc} - -% make sure that loooong URLs always break -\usepackage{xurl} -% make sure all float stay in their respective chapter -%\usepackage[chapter]{placeins} - -% make enough room for the auto-generated header content -\setlength{\headheight}{13.6pt} - -\usepackage{xcolor} -\definecolor{dataladyellow}{HTML}{FFA200} -\definecolor{dataladblue}{HTML}{7FD5FF} -\definecolor{dataladgray}{HTML}{333333} -\definecolor{windowsblue}{HTML}{126e12} -\definecolor{windowsgreen}{HTML}{66CC33} -\definecolor{windowsyellow}{HTML}{FFCC00} - -% nice boxes -\usepackage[skins,breakable,many]{tcolorbox} -\tcbset{breakable} -\tcbset{drop lifted shadow} -\tcbset{sharp corners} -\tcbset{fonttitle=\bfseries} - -\tcbset{% -ribbon win/.style={overlay={ - \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] - \path(0,0) node[inner sep=0] {\includegraphics{win_boxicon}}; - \end{scope}}} -} -\tcbset{% -ribbon git/.style={overlay={ - \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] - \path(0,0) node[inner sep=0] {\includegraphics{git_boxicon}}; - \end{scope}}} -} -\tcbset{% -ribbon more/.style={overlay={ - \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] - \path(0,0) node[inner sep=0] {\includegraphics{more_boxicon}}; - \end{scope}}} -} -\tcbset{% -ribbon important/.style={overlay={ - \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] - \path(0,0) node[inner sep=0] {\includegraphics{important_boxicon}}; - \end{scope}}} -} - -\newcounter{HandbookWIN}[chapter] -\renewcommand\theHandbookWIN{W\arabic{chapter}.\arabic{HandbookWIN}} -\newtcolorbox[% - use counter*=HandbookWIN, - number within=chapter, - list inside=windowswits]{windowswit}[2][]{% - enhanced, ribbon win, title={#2}, - coltitle=dataladgray, - colbacktitle=windowsgreen, - colframe=windowsgreen!70!black, #1 -} -\newcounter{HandbookGIT}[chapter] -\renewcommand\theHandbookGIT{G\arabic{chapter}.\arabic{HandbookGIT}} -\newtcolorbox[% - use counter*=HandbookGIT, - number within=chapter, - list inside=gitusernotes]{gitusernote}[2][]{% - enhanced, ribbon git, title={#2}, - coltitle=dataladgray, - colbacktitle=dataladblue, - colframe=dataladblue!70!black, #1 -} -\newcounter{HandbookFOM}[chapter] -\renewcommand\theHandbookFOM{M\arabic{chapter}.\arabic{HandbookFOM}} -\newtcolorbox[ - use counter*=HandbookFOM, - number within=chapter, - list inside=findoutmores]{findoutmore}[2][]{% - enhanced, ribbon more, title={#2}, - coltitle=dataladgray, - colbacktitle=dataladyellow, - colframe=dataladyellow!70!black, #1 -} -% unnumbered, they are short and placed at the exact position -% must change we there are in-text references -\newtcolorbox[ - number within=chapter, - list inside=importantnotes]{importantnote}[2][]{% - enhanced, ribbon important, title={#2}, - coltitle=white, - colbacktitle=dataladgray, - colframe=dataladgray!70!black, #1 + 'preamble': r'\input{preamble_end.sty}', + 'maketitle': + '%s%s%s\n\\input{titlepage.sty}' % ( + r'\newcommand{\withauthors}{', + ', '.join('\\mbox{%s}' % a for a in authors[1:-1]), + '}', + ), } -\setcounter{tocdepth}{1} -\setcounter{secnumdepth}{1} - -\numberwithin{table}{chapter} -\numberwithin{figure}{chapter} - -% natural spacing between (long) numbers and titles in -% any TOC -\renewcommand{\numberline}[1]{#1~} - - -\newcommand{\findoutmoreiconinline}{\raisebox{-.1em}{\includegraphics[height=.9em]{more_boxicon_inline}}~} -\newcommand{\windowswiticoninline}{\raisebox{-.3em}{\includegraphics[height=1.2em]{win_boxicon}}~} - -% make :term: references visually distinct in a print -\renewcommand{\sphinxtermref}[1]{\textsc{#1}} -""", -} - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - # If false, no module index is generated. #latex_domain_indices = True diff --git a/docs/latex/preamble_end.sty b/docs/latex/preamble_end.sty new file mode 100644 index 000000000..a092af8f9 --- /dev/null +++ b/docs/latex/preamble_end.sty @@ -0,0 +1,115 @@ +\usepackage[labelfont=bf,singlelinecheck=false]{caption} +\renewcommand{\sphinxstyletheadfamily}{\bfseries} +\usepackage{charter} +\usepackage[defaultsans]{lato} +\usepackage{inconsolata} +\usepackage[hang,flushmargin,multiple]{footmisc} + +% make sure that loooong URLs always break +\usepackage{xurl} +% make sure all float stay in their respective chapter +%\usepackage[chapter]{placeins} + +% make enough room for the auto-generated header content +\setlength{\headheight}{13.6pt} + +\usepackage{xcolor} +\definecolor{dataladyellow}{HTML}{FFA200} +\definecolor{dataladblue}{HTML}{7FD5FF} +\definecolor{dataladgray}{HTML}{333333} +\definecolor{windowsblue}{HTML}{126e12} +\definecolor{windowsgreen}{HTML}{66CC33} +\definecolor{windowsyellow}{HTML}{FFCC00} + +% nice boxes +\usepackage[skins,breakable,many]{tcolorbox} +\tcbset{breakable} +\tcbset{drop lifted shadow} +\tcbset{sharp corners} +\tcbset{fonttitle=\bfseries} + +\tcbset{% +ribbon win/.style={overlay={ + \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] + \path(0,0) node[inner sep=0] {\includegraphics{win_boxicon}}; + \end{scope}}} +} +\tcbset{% +ribbon git/.style={overlay={ + \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] + \path(0,0) node[inner sep=0] {\includegraphics{git_boxicon}}; + \end{scope}}} +} +\tcbset{% +ribbon more/.style={overlay={ + \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] + \path(0,0) node[inner sep=0] {\includegraphics{more_boxicon}}; + \end{scope}}} +} +\tcbset{% +ribbon important/.style={overlay={ + \begin{scope}[shift={([xshift=-5mm,yshift=-3mm]frame.north west)}] + \path(0,0) node[inner sep=0] {\includegraphics{important_boxicon}}; + \end{scope}}} +} + +\newcounter{HandbookWIN}[chapter] +\renewcommand\theHandbookWIN{W\arabic{chapter}.\arabic{HandbookWIN}} +\newtcolorbox[% + use counter*=HandbookWIN, + number within=chapter, + list inside=windowswits]{windowswit}[2][]{% + enhanced, ribbon win, title={#2}, + coltitle=dataladgray, + colbacktitle=windowsgreen, + colframe=windowsgreen!70!black, #1 +} +\newcounter{HandbookGIT}[chapter] +\renewcommand\theHandbookGIT{G\arabic{chapter}.\arabic{HandbookGIT}} +\newtcolorbox[% + use counter*=HandbookGIT, + number within=chapter, + list inside=gitusernotes]{gitusernote}[2][]{% + enhanced, ribbon git, title={#2}, + coltitle=dataladgray, + colbacktitle=dataladblue, + colframe=dataladblue!70!black, #1 +} +\newcounter{HandbookFOM}[chapter] +\renewcommand\theHandbookFOM{M\arabic{chapter}.\arabic{HandbookFOM}} +\newtcolorbox[ + use counter*=HandbookFOM, + number within=chapter, + list inside=findoutmores]{findoutmore}[2][]{% + enhanced, ribbon more, title={#2}, + coltitle=dataladgray, + colbacktitle=dataladyellow, + colframe=dataladyellow!70!black, #1 +} +% unnumbered, they are short and placed at the exact position +% must change we there are in-text references +\newtcolorbox[ + number within=chapter, + list inside=importantnotes]{importantnote}[2][]{% + enhanced, ribbon important, title={#2}, + coltitle=white, + colbacktitle=dataladgray, + colframe=dataladgray!70!black, #1 +} + +\setcounter{tocdepth}{1} +\setcounter{secnumdepth}{1} + +\numberwithin{table}{chapter} +\numberwithin{figure}{chapter} + +% natural spacing between (long) numbers and titles in +% any TOC +\renewcommand{\numberline}[1]{#1~} + + +\newcommand{\findoutmoreiconinline}{\raisebox{-.1em}{\includegraphics[height=.9em]{more_boxicon_inline}}~} +\newcommand{\windowswiticoninline}{\raisebox{-.3em}{\includegraphics[height=1.2em]{win_boxicon}}~} + +% make :term: references visually distinct in a print +\renewcommand{\sphinxtermref}[1]{\textsc{#1}} diff --git a/docs/latex/preamble_start.sty b/docs/latex/preamble_start.sty new file mode 100644 index 000000000..4bdf68e74 --- /dev/null +++ b/docs/latex/preamble_start.sty @@ -0,0 +1 @@ +\PassOptionsToPackage{svgnames}{xcolor} diff --git a/docs/latex/titlepage.sty b/docs/latex/titlepage.sty new file mode 100644 index 000000000..979e040d1 --- /dev/null +++ b/docs/latex/titlepage.sty @@ -0,0 +1,17 @@ +\begin{titlepage} +\raggedleft +\rule{1pt}{\textheight} +\hspace{0.05\textwidth} +\parbox[b]{0.75\textwidth}{ +\hfill{\footnotesize \version}\\[1\baselineskip] +\includegraphics[width=0.75\textwidth]{logo.pdf}\\ +{\Huge\textbf{Handbook}}\\ +{\Large Introduction \textbullet\ Advanced topics \textbullet\ Use cases}\\[2\baselineskip] +{\Large\textsc{Adina~Wagner \& Michael~Hanke}\\[1\baselineskip] +{\small \textit{with}}\\[1\baselineskip] +{ +\raggedright +\withauthors\\ +}} +} +\end{titlepage} From fd66eea57132ca6e757d58cf23d318a6ca54fd81 Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Mon, 7 Aug 2023 19:28:43 +0200 Subject: [PATCH 04/33] Factor out LaTeX font setup and enable microtype --- docs/conf.py | 8 +++++--- docs/latex/fontpkg.sty | 4 ++++ docs/latex/preamble_end.sty | 6 ++---- 3 files changed, 11 insertions(+), 7 deletions(-) create mode 100644 docs/latex/fontpkg.sty diff --git a/docs/conf.py b/docs/conf.py index 6cd1e2b8c..dc94cdf8f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -343,6 +343,7 @@ # the following files are included in the main latex document # in the order with which the are listed here 'latex/preamble_start.sty', + 'latex/fontpkg.sty', 'latex/preamble_end.sty', 'latex/titlepage.sty', ] @@ -354,6 +355,10 @@ 'papersize': 'a4paper', 'pointsize': '11pt', 'figure_align': 'htbp', + 'extraclassoptions': 'openany,twoside', + 'passoptionstopackages': r'\input{preamble_start.sty}', + 'fontpkg': r'\input{fontpkg.sty}', + 'fncychap': r'\usepackage[Bjarne]{fncychap}', 'sphinxsetup': r""" verbatimwithframe=false,% VerbatimColor={rgb}{1,1,1},% @@ -369,9 +374,6 @@ cautionBorderColor={named}{Cyan},% cautionBgColor={named}{LightCyan}% """, - 'extraclassoptions': 'openany,twoside', - 'passoptionstopackages': r'\input{preamble_start.sty}', - 'fncychap': r'\usepackage[Bjarne]{fncychap}', 'preamble': r'\input{preamble_end.sty}', 'maketitle': '%s%s%s\n\\input{titlepage.sty}' % ( diff --git a/docs/latex/fontpkg.sty b/docs/latex/fontpkg.sty new file mode 100644 index 000000000..62d5a224f --- /dev/null +++ b/docs/latex/fontpkg.sty @@ -0,0 +1,4 @@ +\usepackage{charter} +\usepackage[defaultsans]{lato} +\usepackage{inconsolata} +\usepackage{microtype} diff --git a/docs/latex/preamble_end.sty b/docs/latex/preamble_end.sty index a092af8f9..7ddd2fb5b 100644 --- a/docs/latex/preamble_end.sty +++ b/docs/latex/preamble_end.sty @@ -1,8 +1,6 @@ -\usepackage[labelfont=bf,singlelinecheck=false]{caption} \renewcommand{\sphinxstyletheadfamily}{\bfseries} -\usepackage{charter} -\usepackage[defaultsans]{lato} -\usepackage{inconsolata} + +\usepackage[labelfont=bf,singlelinecheck=false]{caption} \usepackage[hang,flushmargin,multiple]{footmisc} % make sure that loooong URLs always break From e0692a9d780e5ee670f2241e3390a781ab190034 Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Mon, 7 Aug 2023 19:30:09 +0200 Subject: [PATCH 05/33] Group sphinx macro redefinitions --- docs/latex/preamble_end.sty | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/latex/preamble_end.sty b/docs/latex/preamble_end.sty index 7ddd2fb5b..5b4ed69e0 100644 --- a/docs/latex/preamble_end.sty +++ b/docs/latex/preamble_end.sty @@ -1,4 +1,7 @@ \renewcommand{\sphinxstyletheadfamily}{\bfseries} +% make :term: references visually distinct in a print +\renewcommand{\sphinxtermref}[1]{\textsc{#1}} + \usepackage[labelfont=bf,singlelinecheck=false]{caption} \usepackage[hang,flushmargin,multiple]{footmisc} @@ -108,6 +111,3 @@ ribbon important/.style={overlay={ \newcommand{\findoutmoreiconinline}{\raisebox{-.1em}{\includegraphics[height=.9em]{more_boxicon_inline}}~} \newcommand{\windowswiticoninline}{\raisebox{-.3em}{\includegraphics[height=1.2em]{win_boxicon}}~} - -% make :term: references visually distinct in a print -\renewcommand{\sphinxtermref}[1]{\textsc{#1}} From 3585a3a57bf49f4fc60160927db9bb2576f2d5f7 Mon Sep 17 00:00:00 2001 From: Michael Hanke Date: Tue, 8 Aug 2023 17:34:45 +0200 Subject: [PATCH 06/33] Improve command output truncating MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - the `REDACTED` placeholder is replaced by a UTF-scissors (✂) wrapping of the replaced/masked item - whenever an annex-key path is found (double annex-key), it is replaced by the key shown just once and a `/✂/` prefix, to indicate that something was removed Both changes help readability by limiting line-length. --- docs/conf.py | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index dc94cdf8f..95500d979 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,26 +34,31 @@ autorunrecord_line_replace = [ # trailing space removal (r'[ ]+$', ''), + # strip the keydir for MD5(E) or SHA1(E) annex keys + # the keydir is identical to the annex key name, but consumes + # a lot of space. we replace it with a UTF scissors icon + (r'(?P.*)/(?P[MD5SHA1]+[E-]+s[0-9]+--[0-9a-f]{32,40})(?P[^/]*)/(?P=key)(?P=ext)(?P.*)', + r'\g/✂/\g\g\g'), # Python debug output will contain random memory locations - (r'object at 0x[0-9a-f]{12}>', 'object at REDACTED-MEMORYADDRESS'), + (r'object at 0x[0-9a-f]{12}>', 'object at ✂MEMORYADDRESS✂'), # branch state indicators will always be different for git-annex # (branch contains timestamps) - (r'git-annex@[0-9a-f]{7}', 'git-annex@'), + (r'git-annex@[0-9a-f]{7}', 'git-annex@✂GITSHA✂'), (r'refs/heads/git-annex(?P[ ]+)[0-9a-f]{7}\.\.[0-9a-f]{7}', - 'refs/heads/git-annex\gFROM..TO (REDACTED)'), + 'refs/heads/git-annex\g✂FROM✂..✂TO✂'), # ls -l output will have times and user names # normalize to 'elena' and the "standard timestamp" # this only works when ls --time-style=long-iso was used (r'(?P[-ldrwx]{10})[ ]+(?P[^ ]+)[ ]+(?P[^ ]+)[ ]+(?P[^ ]+)[ ]+(?P[^ ]+)[ ]+(?P[^ ]+)[ ]+(?P