From 753672d2259e6b7cfc9f11cfc809293fa896f6e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Albin=20Ahlb=C3=A4ck?= Date: Mon, 11 Apr 2022 05:09:56 +0200 Subject: [PATCH] Format online documentation Main goal to be more readable. Specifically: - Make pages look more paper-like by * having margins for the text on the "paper" and * applying a maximum width for the "paper". Here the maximum width of the text were set such code blocks of 79 column width were generated without any scroll to the sides. Moreover, the margins were set such that they can get smaller when the screen size is reduced (in order to not have half the screen consisting of margins). - Change fonts to the system defaults in order to let readers use their favorite fonts. - Change to: * Serif in body text. * Sans-serif almost everywhere else. I did this as I think it is easier to read texts with serif in comparison to sans-serif, and since it looks better when switching to and from the math Computer Modern Roman used by MathJax which is of serif-type. - Reduce size of large texts. Most apparent example is the headers as they used to be overwhelmingly large. - Remove box around inline code. As the documentation is written as a text, code should only be considered as another font family, similar to how italic/oblique is used to emphasize things and how italic symbols are used in mathematics: It is simply another "mode" in the text. - Insert spacing between items in the sidebar as they were too close to each other. - Make "Note"-boxes have justified text, like the body text. - Make MathJax have a similar font size as regular text. - Left-align the table of content instead of it being justified. NOTE: Some things in the documentation should be changed in order to look the best. One of these is to use monospace/inline code when referring to a computer variable. Another thing is to use monospace for C-files (*.c, *.h) in the headers. Optionally, one can also start using monospace when referring to websites and emails; I need to think about how to do this in practice first (there are multiple options). --- doc/source/_static/default.css | 157 ++++++++++++++++++++++++++++++++- 1 file changed, 156 insertions(+), 1 deletion(-) diff --git a/doc/source/_static/default.css b/doc/source/_static/default.css index 87e80627d..0a71fe1d7 100644 --- a/doc/source/_static/default.css +++ b/doc/source/_static/default.css @@ -13,8 +13,163 @@ ul .toctree-l1 { div.body { min-width: 450px; - max-width: 100%; + max-width: 766px; + padding-left: min(100px, 7%); + padding-right: min(100px, 7%); + padding-top: min(80px, 5.6%); + padding-bottom: min(90px, 6.3%); + margin-left: auto; + margin-right: auto; } li p { margin: 0.2em; } + + +/* +################################################################################ +# set fonts +################################################################################ + +Assuming 12pt font size in KOMA-script, then: + +- 16px is equivalent to \normalsize. (Normal text and \subsubsection) +- 19px is equivalent to \large. (\subsection) +- 23px is equivalent to \Large. (\section) +- 28px is equivalent to \LARGE. (\chapter) +*/ + +p +{ + font-family: serif; + font-style: normal; + font-weight: normal; + font-size: 16px; +} +b +{ + font-family: serif; + font-style: normal; + font-weight: bold; + font-size: 16px; +} +em +{ + font-family: serif; + font-style: normal; + font-style: oblique; + font-size: 16px; +} +pre +{ + font-family: monospace; + font-size: 16px; +} +kbd, code +{ + background-color: rgba(0, 0, 0, 0); /* Transparent */ + font-family: monospace; + font-size: 16px; + padding: 0px; +} + +/* headings */ +div.body h1 /* We let this resemble \chapter */ +{ + font-family: sans-serif; + font-style: normal; + font-weight: normal; + font-size: 28px; +} +div.body h1 code +{ + font-family: monospace; + font-style: normal; + font-weight: bold; + font-size: 28px; +} +div.body h2 /* We let this resemble \section */ +{ + font-family: sans-serif; + font-style: normal; + font-weight: normal; + font-size: 23px; +} +div.body h2 code +{ + font-family: monospace; + font-style: normal; + font-weight: normal; + font-size: 23px; +} +div.body h3 /* We let this resemble \subsection */ +{ + font-family: sans-serif; + font-style: normal; + font-weight: normal; + font-size: 19px; +} +div.body h3 code +{ + font-family: monospace; + font-style: normal; + font-weight: normal; + font-size: 19px; +} + +div.body li +{ + text-align: left; +} + +/* sidebar */ +.sphinxsidebarwrapper li +{ + margin: 3px 0; +} +p.topless +{ + font-family: sans-serif; +} + +/* toctree */ +.toctree-wrapper.compound +{ + font-family: sans-serif; + font-size: 16px; +} +.toctree-wrapper.compound code +{ + font-family: monospace; + font-size: 16px; +} + +/* description lists */ +dt +{ + font-size: 16px; +} +.sig-name +{ + font-size: 16px; +} +.sig-paren +{ + font-size: 16px; +} + +/* note */ +.admonition +{ + text-align: justify; +} + +/* mathjax */ +.MathJax +{ + /* On Albin's system, CMR seems to render math that is a little bit smaller + * than ordinary text. Hence, render a bit larger math than ordinary text. + * This should be okay for other systems as well, as MathJax usually renders + * too large texts (well above this 17/16 ratio). */ + font-size: 17px !important; +}