display line numbers when viewing source code, fix #328 (#385)

mitmproxy · Apr 24, 2022 · 163ec0d · 163ec0d
1 parent b523c58
commit 163ec0d
Show file tree

Hide file tree

Showing 23 changed files with 3,732 additions and 3,706 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,13 +2,15 @@
 
 # Unreleased: pdoc next
 
+ - Display line numbers when viewing source code.
+   ([#328](https://github.com/mitmproxy/pdoc/issues/328), [@mhils](https://github.com/mhils))
  - Fix catastrophic backtracking in a markdown2 regex that processes pyshell examples.
    ([#376](https://github.com/mitmproxy/pdoc/issues/376), [@Andrew-Sheridan](https://github.com/Andrew-Sheridan) and [@mhils](https://github.com/mhils))
  - pdoc now uses the submodule name in the rendered sidebar, rather than the full import path. 
    ([#374](https://github.com/mitmproxy/pdoc/issues/374), [@jacksund](https://github.com/jacksund))
  - Fix a bug where explicit links were rendered incorrectly.
    ([#382](https://github.com/mitmproxy/pdoc/issues/382), [@mhils](https://github.com/mhils))
- - Fix compatibility with pygments 2.12.
+ - Fix compatibility with Pygments 2.12.
    ([#384](https://github.com/mitmproxy/pdoc/issues/384), [@mhils](https://github.com/mhils))
 
 # 2022-04-06: pdoc 11.0.0

diff --git a/pdoc/render_helpers.py b/pdoc/render_helpers.py
@@ -3,8 +3,8 @@
 import os
 import re
 import warnings
-from contextlib import contextmanager
 from collections.abc import Collection, Iterable, Mapping
+from contextlib import contextmanager
 from unittest.mock import patch
 
 import pygments.formatters.html
@@ -30,7 +30,11 @@
 The pygments lexer used for pdoc.render_helpers.highlight.
 Overwrite this to configure pygments lexing.
 """
-formatter = pygments.formatters.html.HtmlFormatter(cssclass="pdoc-code codehilite")
+formatter = pygments.formatters.html.HtmlFormatter(
+    cssclass="pdoc-code codehilite",
+    linenos="inline",
+    anchorlinenos=True,
+)
 """
 The pygments formatter used for pdoc.render_helpers.highlight. 
 Overwrite this to configure pygments highlighting.
@@ -58,9 +62,19 @@
 
 
 @cache
-def highlight(code: str) -> str:
-    """Highlight a piece of Python code using pygments."""
-    return Markup(pygments.highlight(code, lexer, formatter))
+def highlight(doc: pdoc.doc.Doc) -> str:
+    """Highlight the source code of a documentation object using pygments."""
+    if isinstance(doc, str):  # pragma: no cover
+        warnings.warn(
+            "Passing a string to the `highlight` render helper is deprecated, pass a pdoc.doc.Doc object instead.",
+            DeprecationWarning,
+        )
+        return Markup(pygments.highlight(doc, lexer, formatter))
+
+    # set up correct line numbers and anchors
+    formatter.linespans = doc.qualname or "L"
+    formatter.linenostart = doc.source_lines[0] if doc.source_lines else 1
+    return Markup(pygments.highlight(doc.source, lexer, formatter))
 
 
 @cache

diff --git a/pdoc/templates/content.css b/pdoc/templates/content.css
@@ -200,17 +200,27 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
 .pdoc h3:target,
 .pdoc h4:target,
 .pdoc h5:target,
-.pdoc h6:target {
+.pdoc h6:target,
+.pdoc .pdoc-code > pre > span:target {
     background-color: var(--active);
     box-shadow: -1rem 0 0 0 var(--active);
 }
 
+.pdoc .pdoc-code > pre > span:target {
+    /* make the highlighted line full width so that the background extends */
+    display: block;
+}
+
 .pdoc div:target > .attr,
 .pdoc section:target > .attr,
 .pdoc dd:target > a {
     background-color: var(--active);
 }
 
+.pdoc * {
+    scroll-margin: 2rem;
+}
+
 .pdoc .attr:hover {
     filter: contrast(0.95);
 }

diff --git a/pdoc/templates/default/module.html.jinja2 b/pdoc/templates/default/module.html.jinja2
@@ -273,7 +273,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     {% if show_source and doc.source %}
         <details>
             <summary>View Source</summary>
-            {{ doc.source | highlight }}
+            {{ doc | highlight }}
         </details>
     {% endif %}
 {% enddefaultmacro %}

diff --git a/setup.py b/setup.py
@@ -52,7 +52,7 @@
     python_requires=">=3.7",
     install_requires=[
         "Jinja2 >= 2.11.0",
-        "pygments",
+        "pygments >= 2.12.0",
         "MarkupSafe",
         "astunparse; python_version<'3.9'",
     ],

diff --git a/test/testdata/demo.html b/test/testdata/demo.html
diff --git a/test/testdata/demo_eager.html b/test/testdata/demo_eager.html
diff --git a/test/testdata/demo_long.html b/test/testdata/demo_long.html
diff --git a/test/testdata/demopackage.html b/test/testdata/demopackage.html
diff --git a/test/testdata/demopackage_dir.html b/test/testdata/demopackage_dir.html
diff --git a/test/testdata/example_customtemplate.html b/test/testdata/example_customtemplate.html
diff --git a/test/testdata/example_darkmode.html b/test/testdata/example_darkmode.html
diff --git a/test/testdata/example_mkdocs.html b/test/testdata/example_mkdocs.html
diff --git a/test/testdata/flavors_google.html b/test/testdata/flavors_google.html
diff --git a/test/testdata/flavors_numpy.html b/test/testdata/flavors_numpy.html
diff --git a/test/testdata/flavors_rst.html b/test/testdata/flavors_rst.html
diff --git a/test/testdata/math_demo.html b/test/testdata/math_demo.html
diff --git a/test/testdata/misc.html b/test/testdata/misc.html
diff --git a/test/testdata/misc_py310.html b/test/testdata/misc_py310.html
diff --git a/test/testdata/misc_py39.html b/test/testdata/misc_py39.html
diff --git a/test/testdata/render_options.html b/test/testdata/render_options.html
diff --git a/test/testdata/top_level_reimports.html b/test/testdata/top_level_reimports.html
diff --git a/test/testdata/type_checking_imports.html b/test/testdata/type_checking_imports.html