From a5dd98ac1bde58a79b105ed44952628525c27f6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= <pspacek@isc.org>
Date: Tue, 10 May 2022 16:53:40 +0200
Subject: [PATCH 1/2] Allow wrapping for ARM table content

RTD style default never wraps <th> and <td> elements and that just does
not work for real sentences or any other long lines.

We can reconsider styling some tables separately, but at the moment we
do not have use for tables with long but unwrappable lines so it's
easier to allow wrapping globally.
---
 doc/arm/Makefile.am        |  1 +
 doc/arm/_static/custom.css | 17 +++++++++++++++++
 doc/arm/conf.py            |  4 ++++
 3 files changed, 22 insertions(+)
 create mode 100644 doc/arm/_static/custom.css

diff --git a/doc/arm/Makefile.am b/doc/arm/Makefile.am
index e8024040f0..798d6ba839 100644
--- a/doc/arm/Makefile.am
+++ b/doc/arm/Makefile.am
@@ -61,6 +61,7 @@ EXTRA_DIST =					\
 	troubleshooting.inc.rst			\
 	tsig.inc.rst				\
 	zones.inc.rst				\
+	_static/custom.css			\
 	../dnssec-guide				\
 	../misc/acl.grammar.rst			\
 	../misc/controls.grammar.rst		\
diff --git a/doc/arm/_static/custom.css b/doc/arm/_static/custom.css
new file mode 100644
index 0000000000..e81d66d321
--- /dev/null
+++ b/doc/arm/_static/custom.css
@@ -0,0 +1,17 @@
+/*
+Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+
+SPDX-License-Identifier: MPL-2.0
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0.  If a copy of the MPL was not distributed with this
+file, you can obtain one at https://mozilla.org/MPL/2.0/.
+
+See the COPYRIGHT file distributed with this work for additional
+information regarding copyright ownership.
+*/
+
+/* make table content wrappable */
+.wy-table-responsive table td {
+    white-space:normal;
+}
diff --git a/doc/arm/conf.py b/doc/arm/conf.py
index 60131b41f6..403b6cf529 100644
--- a/doc/arm/conf.py
+++ b/doc/arm/conf.py
@@ -154,6 +154,10 @@ master_doc = 'index'
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_css_files = [
+    'custom.css'
+]
 
 # -- Options for EPUB output -------------------------------------------------
 

From 833af31e7b83784e1bdfb49a43974810a9ee3dd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= <pspacek@isc.org>
Date: Fri, 6 May 2022 18:44:15 +0200
Subject: [PATCH 2/2] ARM style change: render literals in black color

After enormous amount of bikesheding about colors we decided to override
ReadTheDocs default style for literals (``literal`` in the RST markup).

Justification:
- The default RTD "light red literal on white background" is hard to
  read.  https://webaim.org/resources/contrastchecker/ reports that text
  colored as rgb(231, 76, 60) on white background has insufficient
  contrast.
- The ARM has enormous amount of literals all over the place and thus
  one sentence can contain several black/red/black color changes. This
  is distracting. As a consequence, the ARM looks like a Geronimo
  Stilton book.

What we experimented with as replacements for red:
- Green - way too distracting
- Blue - too similar to "usual clickable link"
- Violet - too Geronimo Stilton style
- Brown - better but still distracting

After all the bikesheding we settled on black, i.e. the same as all
"normal" text. I.e. the color is now the same and literals are denoted
by monospaced font and a box around the literal. This has best contrast
and is way less distracting than it used to be.

This lead to a new problem: Internal references to "term definitions"
defined using directives like .. option:: were rendered almost the same
as literals:
- References: monospaced + box + bold + clickable
- Literals: monospaced + box To distinguish these two we added black
  dotted underline to clickable references.

I hereby declare the bikeshed painted.
---
 doc/arm/_static/custom.css | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/arm/_static/custom.css b/doc/arm/_static/custom.css
index e81d66d321..86f030fd3c 100644
--- a/doc/arm/_static/custom.css
+++ b/doc/arm/_static/custom.css
@@ -15,3 +15,11 @@ information regarding copyright ownership.
 .wy-table-responsive table td {
     white-space:normal;
 }
+
+/* readability improvements */
+.rst-content code.literal {
+    color: black;
+}
+.rst-content code.xref {
+    text-decoration: underline dotted gray;
+}