template improvements, fix #346

CHANGELOG.md

@@ -2,6 +2,28 @@
 
 # Unreleased: pdoc next
 
+ - Template improvements may require adjustments to custom templates. Users who do not use custom templates are
+   unaffected. ([#346](https://github.com/mitmproxy/pdoc/issues/346))
+   - Users who embed pdoc's output into other systems: The main layout (sidebar/content) is now part of
+     [`frame.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/default/frame.html.jinja2)
+     instead of
+     [`module.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/default/module.html.jinja2).
+     This allows
+     [`index.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/default/index.html.jinja2)
+     to cleanly extend `frame.html.jinja2` instead of patching `module.html.jinja2`.
+   - Users who customized pdoc's CSS: CSS style definitions moved from `module.html.jinja2` into individual CSS files,
+     namely
+     [`theme.css`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/theme.css),
+     [`layout.css`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/layout.css), and
+     [`content.css`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/content.css). You can now either
+     provide replacements for these files directly, or
+     [append custom styles to the `style` block](https://github.com/mitmproxy/pdoc/blob/main/examples/custom-template/module.html.jinja2)
+     . The existing Jinja2 blocks `style_pdoc`, `style_theme`, `style_layout`, `style_content` are deprecated, see
+     [`module.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/default/module.html.jinja2)
+     for details.
+   - Users who customized `syntax-highlighting.css`: pdoc now consistently uses `.pdoc-code` instead of `.pdoc`
+     or `.codehilite` for syntax highlighting. `.codehilite` is deprecated but will continue to work, giving custom
+     templates time to migrate.
  - Submodules that are mentioned in `__all__` are not listed as part of the module contents anymore. Instead, they
    are listed in the navigation. This now matches the behavior as if `__all__` were not specified.
    If this affects you, please leave feedback in [#341](https://github.com/mitmproxy/pdoc/issues/341).

examples/dark-mode/README.md

@@ -2,8 +2,8 @@
 
 [**Demo**](https://pdoc.dev/docs/dark-mode/demo.html)
 
-This is an example showing how to style pdoc in dark mode using a custom template.
-pdoc defines all colors as CSS variables, so we only need to adjust pdoc's color scheme
-and pygments' syntax highlighting theme.
+This is an example showing how to style pdoc in dark mode using custom stylesheets.
+pdoc defines all colors as CSS variables, so we only need to adjust pdoc's color scheme (`theme.css`)
+and pygments' syntax highlighting theme (`syntax-highlighting.css`).
 
 Run `cd examples/dark-mode && pdoc -t . pdoc` to see it in action!

examples/dark-mode/syntax-highlighting.css

@@ -1,78 +1,80 @@
 /* monokai color scheme, see pdoc/template/README.md */
 pre { line-height: 125%; }
-td.linenos pre { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; }
-span.linenos { color: #000000; background-color: #f0f0f0; padding-left: 5px; padding-right: 5px; }
-td.linenos pre.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
-span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
-.pdoc .hll { background-color: #49483e }
-.pdoc { background: #272822; color: #f8f8f2 }
-.pdoc .c { color: #75715e } /* Comment */
-.pdoc .err { color: #960050; background-color: #1e0010 } /* Error */
-.pdoc .k { color: #66d9ef } /* Keyword */
-.pdoc .l { color: #ae81ff } /* Literal */
-.pdoc .n { color: #f8f8f2 } /* Name */
-.pdoc .o { color: #f92672 } /* Operator */
-.pdoc .p { color: #f8f8f2 } /* Punctuation */
-.pdoc .ch { color: #75715e } /* Comment.Hashbang */
-.pdoc .cm { color: #75715e } /* Comment.Multiline */
-.pdoc .cp { color: #75715e } /* Comment.Preproc */
-.pdoc .cpf { color: #75715e } /* Comment.PreprocFile */
-.pdoc .c1 { color: #75715e } /* Comment.Single */
-.pdoc .cs { color: #75715e } /* Comment.Special */
-.pdoc .gd { color: #f92672 } /* Generic.Deleted */
-.pdoc .ge { font-style: italic } /* Generic.Emph */
-.pdoc .gi { color: #a6e22e } /* Generic.Inserted */
-.pdoc .go { color: #66d9ef } /* Generic.Output */
-.pdoc .gp { color: #f92672; font-weight: bold } /* Generic.Prompt */
-.pdoc .gs { font-weight: bold } /* Generic.Strong */
-.pdoc .gu { color: #75715e } /* Generic.Subheading */
-.pdoc .kc { color: #66d9ef } /* Keyword.Constant */
-.pdoc .kd { color: #66d9ef } /* Keyword.Declaration */
-.pdoc .kn { color: #f92672 } /* Keyword.Namespace */
-.pdoc .kp { color: #66d9ef } /* Keyword.Pseudo */
-.pdoc .kr { color: #66d9ef } /* Keyword.Reserved */
-.pdoc .kt { color: #66d9ef } /* Keyword.Type */
-.pdoc .ld { color: #e6db74 } /* Literal.Date */
-.pdoc .m { color: #ae81ff } /* Literal.Number */
-.pdoc .s { color: #e6db74 } /* Literal.String */
-.pdoc .na { color: #a6e22e } /* Name.Attribute */
-.pdoc .nb { color: #f8f8f2 } /* Name.Builtin */
-.pdoc .nc { color: #a6e22e } /* Name.Class */
-.pdoc .no { color: #66d9ef } /* Name.Constant */
-.pdoc .nd { color: #a6e22e } /* Name.Decorator */
-.pdoc .ni { color: #f8f8f2 } /* Name.Entity */
-.pdoc .ne { color: #a6e22e } /* Name.Exception */
-.pdoc .nf { color: #a6e22e } /* Name.Function */
-.pdoc .nl { color: #f8f8f2 } /* Name.Label */
-.pdoc .nn { color: #f8f8f2 } /* Name.Namespace */
-.pdoc .nx { color: #a6e22e } /* Name.Other */
-.pdoc .py { color: #f8f8f2 } /* Name.Property */
-.pdoc .nt { color: #f92672 } /* Name.Tag */
-.pdoc .nv { color: #f8f8f2 } /* Name.Variable */
-.pdoc .ow { color: #f92672 } /* Operator.Word */
-.pdoc .w { color: #f8f8f2 } /* Text.Whitespace */
-.pdoc .mb { color: #ae81ff } /* Literal.Number.Bin */
-.pdoc .mf { color: #ae81ff } /* Literal.Number.Float */
-.pdoc .mh { color: #ae81ff } /* Literal.Number.Hex */
-.pdoc .mi { color: #ae81ff } /* Literal.Number.Integer */
-.pdoc .mo { color: #ae81ff } /* Literal.Number.Oct */
-.pdoc .sa { color: #e6db74 } /* Literal.String.Affix */
-.pdoc .sb { color: #e6db74 } /* Literal.String.Backtick */
-.pdoc .sc { color: #e6db74 } /* Literal.String.Char */
-.pdoc .dl { color: #e6db74 } /* Literal.String.Delimiter */
-.pdoc .sd { color: #e6db74 } /* Literal.String.Doc */
-.pdoc .s2 { color: #e6db74 } /* Literal.String.Double */
-.pdoc .se { color: #ae81ff } /* Literal.String.Escape */
-.pdoc .sh { color: #e6db74 } /* Literal.String.Heredoc */
-.pdoc .si { color: #e6db74 } /* Literal.String.Interpol */
-.pdoc .sx { color: #e6db74 } /* Literal.String.Other */
-.pdoc .sr { color: #e6db74 } /* Literal.String.Regex */
-.pdoc .s1 { color: #e6db74 } /* Literal.String.Single */
-.pdoc .ss { color: #e6db74 } /* Literal.String.Symbol */
-.pdoc .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */
-.pdoc .fm { color: #a6e22e } /* Name.Function.Magic */
-.pdoc .vc { color: #f8f8f2 } /* Name.Variable.Class */
-.pdoc .vg { color: #f8f8f2 } /* Name.Variable.Global */
-.pdoc .vi { color: #f8f8f2 } /* Name.Variable.Instance */
-.pdoc .vm { color: #f8f8f2 } /* Name.Variable.Magic */
-.pdoc .il { color: #ae81ff } /* Literal.Number.Integer.Long */
+span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 20px; }
+.pdoc-code .hll { background-color: #49483e }
+.pdoc-code { background: #272822; color: #f8f8f2 }
+.pdoc-code .c { color: #75715e } /* Comment */
+.pdoc-code .err { color: #960050; background-color: #1e0010 } /* Error */
+.pdoc-code .esc { color: #f8f8f2 } /* Escape */
+.pdoc-code .g { color: #f8f8f2 } /* Generic */
+.pdoc-code .k { color: #66d9ef } /* Keyword */
+.pdoc-code .l { color: #ae81ff } /* Literal */
+.pdoc-code .n { color: #f8f8f2 } /* Name */
+.pdoc-code .o { color: #f92672 } /* Operator */
+.pdoc-code .x { color: #f8f8f2 } /* Other */
+.pdoc-code .p { color: #f8f8f2 } /* Punctuation */
+.pdoc-code .ch { color: #75715e } /* Comment.Hashbang */
+.pdoc-code .cm { color: #75715e } /* Comment.Multiline */
+.pdoc-code .cp { color: #75715e } /* Comment.Preproc */
+.pdoc-code .cpf { color: #75715e } /* Comment.PreprocFile */
+.pdoc-code .c1 { color: #75715e } /* Comment.Single */
+.pdoc-code .cs { color: #75715e } /* Comment.Special */
+.pdoc-code .gd { color: #f92672 } /* Generic.Deleted */
+.pdoc-code .ge { color: #f8f8f2; font-style: italic } /* Generic.Emph */
+.pdoc-code .gr { color: #f8f8f2 } /* Generic.Error */
+.pdoc-code .gh { color: #f8f8f2 } /* Generic.Heading */
+.pdoc-code .gi { color: #a6e22e } /* Generic.Inserted */
+.pdoc-code .go { color: #66d9ef } /* Generic.Output */
+.pdoc-code .gp { color: #f92672; font-weight: bold } /* Generic.Prompt */
+.pdoc-code .gs { color: #f8f8f2; font-weight: bold } /* Generic.Strong */
+.pdoc-code .gu { color: #75715e } /* Generic.Subheading */
+.pdoc-code .gt { color: #f8f8f2 } /* Generic.Traceback */
+.pdoc-code .kc { color: #66d9ef } /* Keyword.Constant */
+.pdoc-code .kd { color: #66d9ef } /* Keyword.Declaration */
+.pdoc-code .kn { color: #f92672 } /* Keyword.Namespace */
+.pdoc-code .kp { color: #66d9ef } /* Keyword.Pseudo */
+.pdoc-code .kr { color: #66d9ef } /* Keyword.Reserved */
+.pdoc-code .kt { color: #66d9ef } /* Keyword.Type */
+.pdoc-code .ld { color: #e6db74 } /* Literal.Date */
+.pdoc-code .m { color: #ae81ff } /* Literal.Number */
+.pdoc-code .s { color: #e6db74 } /* Literal.String */
+.pdoc-code .na { color: #a6e22e } /* Name.Attribute */
+.pdoc-code .nb { color: #f8f8f2 } /* Name.Builtin */
+.pdoc-code .nc { color: #a6e22e } /* Name.Class */
+.pdoc-code .no { color: #66d9ef } /* Name.Constant */
+.pdoc-code .nd { color: #a6e22e } /* Name.Decorator */
+.pdoc-code .ni { color: #f8f8f2 } /* Name.Entity */
+.pdoc-code .ne { color: #a6e22e } /* Name.Exception */
+.pdoc-code .nf { color: #a6e22e } /* Name.Function */
+.pdoc-code .nl { color: #f8f8f2 } /* Name.Label */
+.pdoc-code .nn { color: #f8f8f2 } /* Name.Namespace */
+.pdoc-code .nx { color: #a6e22e } /* Name.Other */
+.pdoc-code .py { color: #f8f8f2 } /* Name.Property */
+.pdoc-code .nt { color: #f92672 } /* Name.Tag */
+.pdoc-code .nv { color: #f8f8f2 } /* Name.Variable */
+.pdoc-code .ow { color: #f92672 } /* Operator.Word */
+.pdoc-code .w { color: #f8f8f2 } /* Text.Whitespace */
+.pdoc-code .mb { color: #ae81ff } /* Literal.Number.Bin */
+.pdoc-code .mf { color: #ae81ff } /* Literal.Number.Float */
+.pdoc-code .mh { color: #ae81ff } /* Literal.Number.Hex */
+.pdoc-code .mi { color: #ae81ff } /* Literal.Number.Integer */
+.pdoc-code .mo { color: #ae81ff } /* Literal.Number.Oct */
+.pdoc-code .sa { color: #e6db74 } /* Literal.String.Affix */
+.pdoc-code .sb { color: #e6db74 } /* Literal.String.Backtick */
+.pdoc-code .sc { color: #e6db74 } /* Literal.String.Char */
+.pdoc-code .dl { color: #e6db74 } /* Literal.String.Delimiter */
+.pdoc-code .sd { color: #e6db74 } /* Literal.String.Doc */
+.pdoc-code .s2 { color: #e6db74 } /* Literal.String.Double */
+.pdoc-code .se { color: #ae81ff } /* Literal.String.Escape */
+.pdoc-code .sh { color: #e6db74 } /* Literal.String.Heredoc */
+.pdoc-code .si { color: #e6db74 } /* Literal.String.Interpol */
+.pdoc-code .sx { color: #e6db74 } /* Literal.String.Other */
+.pdoc-code .sr { color: #e6db74 } /* Literal.String.Regex */
+.pdoc-code .s1 { color: #e6db74 } /* Literal.String.Single */
+.pdoc-code .ss { color: #e6db74 } /* Literal.String.Symbol */
+.pdoc-code .bp { color: #f8f8f2 } /* Name.Builtin.Pseudo */
+.pdoc-code .fm { color: #a6e22e } /* Name.Function.Magic */
+.pdoc-code .vc { color: #f8f8f2 } /* Name.Variable.Class */
+.pdoc-code .vg { color: #f8f8f2 } /* Name.Variable.Global */
+.pdoc-code .vi { color: #f8f8f2 } /* Name.Variable.Instance */
+.pdoc-code .vm { color: #f8f8f2 } /* Name.Variable.Magic */

examples/dark-mode/theme.css

@@ -0,0 +1,20 @@
+:root {
+    --pdoc-background: #212529;
+}
+
+.pdoc {
+    --text: #f7f7f7;
+    --muted: #9d9d9d;
+    --link: #58a6ff;
+    --link-hover: #3989ff;
+    --code: #333;
+    --active: #555;
+
+    --accent: #343434;
+    --accent2: #555;
+
+    --nav-hover: rgba(0, 0, 0, 0.1);
+    --name: #77C1FF;
+    --def: #0cdd0c;
+    --annotation: #00c037;
+}

examples/mkdocs/README.md

@@ -5,7 +5,7 @@ Run `./make.py` to generate the API documentation and then `mkdocs serve` to vie
 
 ## Implementation
 
-The main trick is that we define custom `frame.html.jinja2` and `module.html.jinja2` templates to
+The main trick is that we define a custom `frame.html.jinja2` template to
 remove pdoc's usual HTML code around the main documentation contents. 
 We then invoke pdoc normally and rename the output files to `.md` so that they are picked up by mkdocs.
 mkdocs' Markdown parser accepts the interspersed HTML just fine!

examples/mkdocs/make.py

@@ -8,9 +8,9 @@
 out = here / "docs" / "api"
 shutil.rmtree(out)
 
-# Render pdoc's documentation into docs/api...
+# Render parts of pdoc's documentation into docs/api...
 render.configure(template_directory=here / "pdoc-template")
-pdoc("pdoc", output_directory=out)
+pdoc("pdoc", "!pdoc.", "pdoc.doc", output_directory=out)
 
 # ...and rename the .html files to .md so that mkdocs picks them up!
 for f in out.glob("**/*.html"):

examples/mkdocs/pdoc-template/frame.html.jinja2

@@ -1,7 +1,20 @@
 ---
 title: {{ module.modulename if module else "API Reference" }}
 ---
+
 <div>
-    {% block style %}{% endblock %}
-    {% block body %}{% endblock %}
+    {% block content %}{% endblock %}
+
+    {% filter minify_css %}
+        {% block style %}
+            {#
+            The important part is that we leave out layout.css here.
+            Ideally we would still include Bootstrap Reboot, but that breaks mkdocs' theme.
+            <style>{% include "resources/bootstrap-reboot.min.css" %}</style>
+            #}
+            <style>{% include "syntax-highlighting.css" %}</style>
+            <style>{% include "theme.css" %}</style>
+            <style>{% include "content.css" %}</style>
+        {% endblock %}
+    {% endfilter %}
 </div>

pdoc/render_helpers.py

@@ -29,16 +29,18 @@
 The pygments lexer used for pdoc.render_helpers.highlight.
 Overwrite this to configure pygments lexing.
 """
-formatter = pygments.formatters.html.HtmlFormatter(cssclass="codehilite")
+formatter = pygments.formatters.html.HtmlFormatter(cssclass="pdoc-code codehilite")
 """
 The pygments formatter used for pdoc.render_helpers.highlight. 
 Overwrite this to configure pygments highlighting.
+
+The usage of the `.codehilite` CSS selector in custom templates is deprecated since pdoc 10, use `.pdoc-code` instead.
 """
 
 markdown_extensions = {
     "code-friendly": None,
     "cuddled-lists": None,
-    "fenced-code-blocks": None,
+    "fenced-code-blocks": {"cssclass": formatter.cssclass},
     "footnotes": None,
     "header-ids": None,
     "pyshell": None,

pdoc/templates/README.md

@@ -16,8 +16,8 @@ The `syntax-highlighting.css` file contains the CSS styles used for syntax highl
 It is generated as follows:
 
 ```
-pygmentize -f html -a .pdoc -S <theme> > syntax-highlighting.css
+pygmentize -f html -a .pdoc-code -S <theme> > default/syntax-highlighting.css
 ```
 
-The default theme is `default`. Alternative color schemes can be tested on 
-[the Pygments website](https://pygments.org/demo/).
+The default theme is `default`, with extended padding added to the `.linenos` class.
+Alternative color schemes can be tested on [the Pygments website](https://pygments.org/demo/).