cafkafk/nixpkgs
cafkafk/nixpkgs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

doc: fix and simplify stylesheets for the manuals, fix nrd bug (#295847)

Browse source 
* doc: fix and simplify stylesheets for the manuals, fix nrd bug

* Add anchorjs script to add links on section headers

* Fix another nrd bug, address style changes

* Use span instead of a for inline span syntax
This commit is contained in:
Daniel Sidhion 2024-03-16 12:16:59 -07:00 committed by GitHub
parent 4645c67723
commit a1581a3647
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 381 additions and 262 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/anchor-use.js Normal file
View file

@ -0,0 +1,3 @@
document.addEventListener('DOMContentLoaded', function(event) {
anchors.add('h1:not(div.note h1, div.warning h1, div.tip h1, div.caution h1, div.important h1), h2:not(div.note h2, div.warning h2, div.tip h2, div.caution h2, div.important h2), h3:not(div.note h3, div.warning h3, div.tip h3, div.caution h3, div.important h3), h4:not(div.note h4, div.warning h4, div.tip h4, div.caution h4, div.important h4), h5:not(div.note h5, div.warning h5, div.tip h5, div.caution h5, div.important h5), h6:not(div.note h6, div.warning h6, div.tip h6, div.caution h6, div.important h6)');
});

9
doc/anchor.min.js vendored Normal file
View file

File diff suppressed because one or more lines are too long

5
doc/default.nix
View file

@ -122,16 +122,17 @@ in pkgs.stdenv.mkDerivation {
${pkgs.documentation-highlighter}/mono-blue.css \ ${pkgs.documentation-highlighter}/mono-blue.css \
${pkgs.documentation-highlighter}/loader.js ${pkgs.documentation-highlighter}/loader.js
cp -t out ./overrides.css ./style.css cp -t out ./style.css ./anchor.min.js ./anchor-use.js
nixos-render-docs manual html \ nixos-render-docs manual html \
--manpage-urls ./manpage-urls.json \ --manpage-urls ./manpage-urls.json \
--revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \ --revision ${pkgs.lib.trivial.revisionWithDefault (pkgs.rev or "master")} \
--stylesheet style.css \ --stylesheet style.css \
--stylesheet overrides.css \
--stylesheet highlightjs/mono-blue.css \ --stylesheet highlightjs/mono-blue.css \
--script ./highlightjs/highlight.pack.js \ --script ./highlightjs/highlight.pack.js \
--script ./highlightjs/loader.js \ --script ./highlightjs/loader.js \
--script ./anchor.min.js \
--script ./anchor-use.js \
--toc-depth 1 \ --toc-depth 1 \
--section-toc-depth 1 \ --section-toc-depth 1 \
manual.md \ manual.md \

22
doc/overrides.css
View file

@ -1,22 +0,0 @@
.docbook .xref img[src^=images\/callouts\/],
.screen img,
.programlisting img,
.literallayout img,
.synopsis img {
width: 1em;
}
.calloutlist img {
width: 1.5em;
}
.prompt,
.screen img,
.programlisting img,
.literallayout img,
.synopsis img {
-moz-user-select: none;
-webkit-user-select: none;
-ms-user-select: none;
user-select: none;
}

583
doc/style.css
View file

@ -1,291 +1,416 @@
/* Copied from http://bakefile.sourceforge.net/, which appears html {
licensed under the GNU GPL. */ line-height: 1.15;
-webkit-text-size-adjust: 100%;
/***************************************************************************
Basic headers and text:
***************************************************************************/
body
{
font-family: "Nimbus Sans L", sans-serif;
font-size: 1em;
background: white;
margin: 2em 1em 2em 1em;
} }
h1, h2, h3, h4 body {
{ margin: 0;
color: #005aa0;
} }
h1 /* title */ .book {
{
font-size: 200%;
}
h2 /* chapters, appendices, subtitle */
{
font-size: 180%;
}
div.book
{
text-align: center;
}
div.book > div
{
/*
* based on https://medium.com/@zkareemz/golden-ratio-62b3b6d4282a
* we do 70 characters per line to fit code listings better
* 70 * (font-size / 1.618)
* expression for emacs:
* (* 70 (/ 1 1.618))
*/
max-width: 43.2em;
text-align: left;
margin: auto; margin: auto;
width: 100%;
} }
/* Extra space between chapters, appendices. */ @media screen and (min-width: 768px) {
div.chapter > div.titlepage h2, div.appendix > div.titlepage h2 .book {
{ max-width: 46rem;
margin-top: 1.5em; }
} }
div.section > div.titlepage h2 /* sections */ @media screen and (min-width: 992px) {
{ .book {
font-size: 150%; max-width: 60rem;
margin-top: 1.5em; }
} }
h3 /* subsections */ @media screen and (min-width: 1200px) {
{ .book {
font-size: 125%; max-width: 73rem;
}
} }
div.simplesect h2 .book .list-of-examples {
{ display: none;
font-size: 110%;
} }
div.appendix h3 h1 {
{ font-size: 2em;
font-size: 150%; margin: 0.67em 0;
margin-top: 1.5em;
} }
div.refnamediv h2, div.refsynopsisdiv h2, div.refsection h2 /* refentry parts */ hr {
{ box-sizing: content-box;
margin-top: 1.4em; height: 0;
font-size: 125%; overflow: visible;
} }
div.refsection h3 pre {
{ font-family: monospace, monospace;
font-size: 110%; font-size: 1em;
} }
a {
/*************************************************************************** background-color: transparent;
Examples:
***************************************************************************/
div.example
{
border: 1px solid #b0b0b0;
padding: 6px 6px;
margin-left: 1.5em;
margin-right: 1.5em;
background: #f4f4f8;
border-radius: 0.4em;
box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
} }
div.example p.title strong {
{ font-weight: bolder;
margin-top: 0em;
} }
div.example pre code {
{ font-family: monospace, monospace;
box-shadow: none; font-size: 1em;
} }
sup {
/*************************************************************************** font-size: 75%;
Screen dumps: line-height: 0;
***************************************************************************/ position: relative;
vertical-align: baseline;
pre.screen, pre.programlisting
{
border: 1px solid #b0b0b0;
padding: 3px 3px;
margin-left: 0.5em;
margin-right: 0.5em;
background: #f4f4f8;
font-family: monospace;
border-radius: 0.4em;
box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
} }
div.example pre.programlisting sup {
{ top: -0.5em;
border: 0px;
padding: 0 0;
margin: 0 0 0 0;
} }
/*************************************************************************** ::-webkit-file-upload-button {
Notes, warnings etc: -webkit-appearance: button;
***************************************************************************/ font: inherit;
.note, .warning
{
border: 1px solid #b0b0b0;
padding: 3px 3px;
margin-left: 1.5em;
margin-right: 1.5em;
margin-bottom: 1em;
padding: 0.3em 0.3em 0.3em 0.3em;
background: #fffff5;
border-radius: 0.4em;
box-shadow: 0.4em 0.4em 0.5em #e0e0e0;
} }
div.note, div.warning pre {
{ overflow: auto;
font-style: italic;
} }
div.note h3, div.warning h3 *,
{ *::before,
color: red; *::after {
box-sizing: border-box;
}
html {
font-size: 100%; font-size: 100%;
padding-right: 0.5em; line-height: 1.77777778;
display: inline;
} }
div.note p, div.warning p @media screen and (min-width: 4000px) {
{ html {
margin-bottom: 0em; background: #000;
} }
div.note h3 + p, div.warning h3 + p html body {
{ margin: auto;
display: inline; max-width: 250rem;
}
} }
div.note h3 @media screen and (max-width: 320px) {
{ html {
color: blue; font-size: calc(16 / 320 * 100vw);
font-size: 100%; }
} }
div.navfooter * body {
{ font-size: 1rem;
font-size: 90%; font-family: 'Roboto', sans-serif;
font-weight: 300;
color: #000000;
background-color: #ffffff;
min-height: 100vh;
display: flex;
flex-direction: column;
} }
@media screen and (max-width: 767.9px) {
/*************************************************************************** body {
Links colors and highlighting: padding-left: 1rem;
***************************************************************************/ padding-right: 1rem;
}
a { text-decoration: none; }
a:hover { text-decoration: underline; }
a:link { color: #0048b3; }
a:visited { color: #002a6a; }
/***************************************************************************
Table of contents:
***************************************************************************/
div.toc
{
font-size: 90%;
} }
div.toc dl a {
{ text-decoration: none;
margin-top: 0em; border-bottom: 1px solid;
margin-bottom: 0em; color: #405d99;
} }
ul {
/*************************************************************************** padding: 0;
Special elements: margin-top: 0;
***************************************************************************/ margin-right: 0;
margin-bottom: 1rem;
tt, code margin-left: 1rem;
{
color: #400000;
} }
.term table {
{
font-weight: bold;
}
div.variablelist dd p, div.glosslist dd p
{
margin-top: 0em;
}
div.variablelist dd, div.glosslist dd
{
margin-left: 1.5em;
}
div.glosslist dt
{
font-style: italic;
}
.varname
{
color: #400000;
}
span.command strong
{
font-weight: normal;
color: #400000;
}
div.calloutlist table
{
box-shadow: none;
}
table
{
border-collapse: collapse; border-collapse: collapse;
box-shadow: 0.4em 0.4em 0.5em #e0e0e0; width: 100%;
margin-bottom: 1rem;
} }
table.simplelist thead th {
{
text-align: left; text-align: left;
color: #005aa0; }
hr {
margin-top: 1rem;
margin-bottom: 1rem;
}
h1 {
font-weight: 800;
line-height: 110%;
font-size: 200%;
margin-bottom: 1rem;
color: #6586c8;
}
h2 {
font-weight: 800;
line-height: 110%;
font-size: 170%;
margin-bottom: 0.625rem;
color: #6586c8;
}
h2:not(:first-child) {
margin-top: 1rem;
}
h3 {
font-weight: 800;
line-height: 110%;
margin-bottom: 1rem;
font-size: 150%;
color: #6586c8;
}
.note h3,
.tip h3,
.warning h3,
.caution h3,
.important h3 {
font-size: 120%;
}
h4 {
font-weight: 800;
line-height: 110%;
margin-bottom: 1rem;
font-size: 140%;
color: #6586c8;
}
h5 {
font-weight: 800;
line-height: 110%;
margin-bottom: 1rem;
font-size: 130%;
color: #6a6a6a;
}
h6 {
font-weight: 800;
line-height: 110%;
margin-bottom: 1rem;
font-size: 120%
}
strong {
font-weight: bold;
}
p {
margin-top: 0;
margin-bottom: 1rem;
}
dt>*:first-child,
dd>*:first-child {
margin-top: 0;
}
dt>*:last-child,
dd>*:last-child {
margin-bottom: 0;
}
pre,
code {
font-family: monospace;
}
code {
color: #ff8657;
background: #f4f4f4;
display: inline-block;
padding: 0 0.5rem;
border: 1px solid #d8d8d8;
border-radius: 0.5rem;
line-height: 1.57777778;
}
div.book .programlisting,
div.appendix .programlisting {
border-radius: 0.5rem;
padding: 1rem;
overflow: auto;
background: #f2f8fd;
color: #000000;
}
div.book .note,
div.book .tip,
div.book .warning,
div.book .caution,
div.book .important,
div.appendix .note,
div.appendix .tip,
div.appendix .warning,
div.appendix .caution,
div.appendix .important {
margin-bottom: 1rem;
border-radius: 0.5rem;
padding: 1.5rem;
overflow: auto;
background: #f4f4f4;
}
div.book .note>.title,
div.book .tip>.title,
div.book .warning>.title,
div.book .caution>.title,
div.book .important>.title,
div.appendix .note>.title,
div.appendix .tip>.title,
div.appendix .warning>.title,
div.appendix .caution>.title,
div.appendix .important>.title {
font-weight: 800;
/* font-family: 'Overpass', serif; */
line-height: 110%;
margin-bottom: 1rem;
color: inherit;
margin-bottom: 0;
}
div.book .note> :first-child,
div.book .tip> :first-child,
div.book .warning> :first-child,
div.book .caution> :first-child,
div.book .important> :first-child,
div.appendix .note> :first-child,
div.appendix .tip> :first-child,
div.appendix .warning> :first-child,
div.appendix .caution> :first-child,
div.appendix .important> :first-child {
margin-top: 0;
}
div.book .note> :last-child,
div.book .tip> :last-child,
div.book .warning> :last-child,
div.book .caution> :last-child,
div.book .important> :last-child,
div.appendix .note> :last-child,
div.appendix .tip> :last-child,
div.appendix .warning> :last-child,
div.appendix .caution> :last-child,
div.appendix .important> :last-child {
margin-bottom: 0;
}
div.book .note,
div.book .tip,
div.appendix .note,
div.appendix .tip {
color: #5277c3;
background: #f2f8fd;
}
div.book .warning,
div.book .caution,
div.appendix .warning,
div.appendix .caution {
color: #cc3900;
background-color: #fff5e1;
}
div.book .section,
div.appendix .section {
margin-top: 2em;
}
div.book div.example,
div.appendix div.example {
margin-top: 1.5em;
}
div.book br.example-break,
div.appendix br.example-break {
display: none;
}
div.book div.footnotes>hr,
div.appendix div.footnotes>hr {
border-color: #d8d8d8;
}
div.book div.footnotes>br,
div.appendix div.footnotes>br {
display: none;
}
div.book dt,
div.appendix dt {
margin-top: 1em;
}
div.book .toc dt,
div.appendix .toc dt {
margin-top: 0;
}
div.book .list-of-examples dt,
div.appendix .list-of-examples dt {
margin-top: 0;
}
div.book code,
div.appendix code {
padding: 0;
border: 0; border: 0;
padding: 5px; background-color: inherit;
background: #fffff5; color: inherit;
font-weight: normal; font-size: 100%;
font-style: italic; -webkit-hyphens: none;
box-shadow: none; -moz-hyphens: none;
margin-bottom: 1em; hyphens: none;
} }
div.navheader table, div.navfooter table { div.book div.toc,
box-shadow: none; div.appendix div.toc {
margin-bottom: 3em;
border-bottom: 0.0625rem solid #d8d8d8;
} }
div.affiliation div.book div.toc dd,
{ div.appendix div.toc dd {
font-style: italic; margin-left: 2em;
}
div.book span.command,
div.appendix span.command {
font-family: monospace;
-webkit-hyphens: none;
-moz-hyphens: none;
hyphens: none;
}
div.book .informaltable th,
div.book .informaltable td,
div.appendix .informaltable th,
div.appendix .informaltable td {
padding: 0.5rem;
} }

7
nixos/doc/manual/default.nix
View file

@ -105,7 +105,9 @@ in rec {
mkdir -p $dst mkdir -p $dst
cp ${../../../doc/style.css} $dst/style.css cp ${../../../doc/style.css} $dst/style.css
cp ${../../../doc/overrides.css} $dst/overrides.css cp ${../../../doc/anchor.min.js} $dst/anchor.min.js
cp ${../../../doc/anchor-use.js} $dst/anchor-use.js
cp -r ${pkgs.documentation-highlighter} $dst/highlightjs cp -r ${pkgs.documentation-highlighter} $dst/highlightjs
${prepareManualFromMD} ${prepareManualFromMD}
@ -115,10 +117,11 @@ in rec {
--revision ${lib.escapeShellArg revision} \ --revision ${lib.escapeShellArg revision} \
--generator "nixos-render-docs ${lib.version}" \ --generator "nixos-render-docs ${lib.version}" \
--stylesheet style.css \ --stylesheet style.css \
--stylesheet overrides.css \
--stylesheet highlightjs/mono-blue.css \ --stylesheet highlightjs/mono-blue.css \
--script ./highlightjs/highlight.pack.js \ --script ./highlightjs/highlight.pack.js \
--script ./highlightjs/loader.js \ --script ./highlightjs/loader.js \
--script ./anchor.min.js \
--script ./anchor-use.js \
--toc-depth 1 \ --toc-depth 1 \
--chunk-toc-depth 1 \ --chunk-toc-depth 1 \
./manual.md \ ./manual.md \

8
pkgs/tools/nix/nixos-render-docs/src/nixos_render_docs/html.py
View file

@ -163,7 +163,7 @@ class HTMLRenderer(Renderer):
# keycap-styled spans. # keycap-styled spans.
(id_part, class_part) = ("", "") (id_part, class_part) = ("", "")
if s := token.attrs.get('id'): if s := token.attrs.get('id'):
id_part = f'<a id="{escape(cast(str, s), True)}" />' id_part = f'<span id="{escape(cast(str, s), True)}"></span>'
if s := token.attrs.get('class'): if s := token.attrs.get('class'):
if s == 'keycap': if s == 'keycap':
class_part = '<span class="keycap"><strong>' class_part = '<span class="keycap"><strong>'
@ -181,7 +181,7 @@ class HTMLRenderer(Renderer):
if hstyle: if hstyle:
hstyle = f'style="{escape(hstyle, True)}"' hstyle = f'style="{escape(hstyle, True)}"'
if anchor := cast(str, token.attrs.get('id', '')): if anchor := cast(str, token.attrs.get('id', '')):
anchor = f'<a id="{escape(anchor, True)}"></a>' anchor = f'<span id="{escape(anchor, True)}"></span>'
result = self._close_headings(hlevel) result = self._close_headings(hlevel)
tag = self._heading_tag(token, tokens, i) tag = self._heading_tag(token, tokens, i)
toc_fragment = self._build_toc(tokens, i) toc_fragment = self._build_toc(tokens, i)
@ -220,7 +220,7 @@ class HTMLRenderer(Renderer):
def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str: def example_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
if id := cast(str, token.attrs.get('id', '')): if id := cast(str, token.attrs.get('id', '')):
id = f'id="{escape(id, True)}"' if id else '' id = f'id="{escape(id, True)}"' if id else ''
return f'<div class="example"><a {id} />' return f'<div class="example"><span {id} ></span>'
def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str: def example_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
return '</div></div><br class="example-break" />' return '</div></div><br class="example-break" />'
def example_title_open(self, token: Token, tokens: Sequence[Token], i: int) -> str: def example_title_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
@ -239,7 +239,7 @@ class HTMLRenderer(Renderer):
) )
def figure_open(self, token: Token, tokens: Sequence[Token], i: int) -> str: def figure_open(self, token: Token, tokens: Sequence[Token], i: int) -> str:
if anchor := cast(str, token.attrs.get('id', '')): if anchor := cast(str, token.attrs.get('id', '')):
anchor = f'<a id="{escape(anchor, True)}"></a>' anchor = f'<span id="{escape(anchor, True)}"></span>'
return f'<div class="figure">{anchor}' return f'<div class="figure">{anchor}'
def figure_close(self, token: Token, tokens: Sequence[Token], i: int) -> str: def figure_close(self, token: Token, tokens: Sequence[Token], i: int) -> str:
return ( return (

2
pkgs/tools/nix/nixos-render-docs/src/tests/test_html.py
View file

@ -167,7 +167,7 @@ def test_full() -> None:
<span class="citerefentry"><span class="refentrytitle">man</span>(1)</span> <span class="citerefentry"><span class="refentrytitle">man</span>(1)</span>
</a> reference </a> reference
</p> </p>
<p><a id="b" />some <a id="a" />nested anchors</p> <p><span id="b"></span>some <span id="a"></span>nested anchors</p>
<p> <p>
<span class="emphasis"><em>emph</em></span>␣ <span class="emphasis"><em>emph</em></span>␣
<span class="strong"><strong>strong</strong></span>␣ <span class="strong"><strong>strong</strong></span>␣