Skip to content

Commit 0086e65

Browse files
HzaCodeHzaCode
authored
Merge pull request #38 from HzaCode/fix/docs-syntax-highlighting
Further improve docs syntax highlighting consistency
2 parents 5406404 + 9bb4e8a commit 0086e65

File tree

6 files changed

+596
-9
lines changed

6 files changed

+596
-9
lines changed

‎.txt with specific version constraints‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
warning: in the working copy of 'docs/source/conf.py', LF will be replaced by CRLF the next time Git touches it
2+
diff --git a/docs/source/conf.py b/docs/source/conf.py
3+
index 3bfafae..2be541c 100644
4+
--- a/docs/source/conf.py
5+
+++ b/docs/source/conf.py
6+
@@ -26,18 +26,22 @@ extensions = [
7+
templates_path = ["_templates"]
8+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
9+
source_suffix = ".rst"
10+
-pygments_style = "default"
11+
+pygments_style = "github-dark"
12+

13+
# -- Syntax highlighting configuration ----------------------------------------
14+
# Ensure consistent syntax highlighting across all code blocks
15+
highlight_language = "python"
16+
highlight_options = {
17+
- 'default': {'stripall': False},
18+
- 'python': {'stripall': False},
19+
- 'bash': {'stripall': False},
20+
- 'text': {'stripall': False},
21+
+ 'default': {'stripnl': True, 'stripall': True},
22+
+ 'python': {'stripnl': True, 'stripall': True},
23+
+ 'bash': {'stripnl': True, 'stripall': True},
24+
+ 'text': {'stripnl': False, 'stripall': False},
25+
+ 'json': {'stripnl': True, 'stripall': True},
26+
}
27+

28+
+# Enable dark theme support for better contrast
29+
+pygments_dark_style = "github-dark"
30+
+
31+
# -- Copy button configuration -----------------------------------------------
32+
# Configure sphinx-copybutton to skip prompts and output
33+
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
34+
@@ -49,6 +53,12 @@ copybutton_remove_prompts = True
35+
html_theme = "sphinx_rtd_theme"
36+
html_static_path = ["_static"]
37+

38+
+# Include custom CSS files for enhanced syntax highlighting
39+
+html_css_files = [
40+
+ 'custom.css',
41+
+ 'syntax_highlighting.css',
42+
+]
43+
+
44+
html_theme_options = {
45+
"collapse_navigation": True,
46+
"navigation_depth" : 2,

‎docs/requirements.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
sphinx
2-
sphinx-rtd-theme
3-
sphinx-copybutton
1+
sphinx>=5.0.0
2+
sphinx-rtd-theme>=1.2.0
3+
sphinx-copybutton>=0.5.0
44

5-
# Required for consistent syntax highlighting
5+
# Required for consistent and enhanced syntax highlighting
66
pygments>=2.17.0

‎docs/source/_static/syntax_highlighting.css‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
/* Enhanced Syntax Highlighting for ChemInformant Documentation */
2+
3+
/* Base code block styling */
4+
.highlight {
5+
background: #f8f9fa !important;
6+
border: 1px solid #e9ecef;
7+
border-radius: 6px;
8+
padding: 1em;
9+
margin: 1em 0;
10+
overflow-x: auto;
11+
font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, 'Courier New', monospace;
12+
font-size: 0.875em;
13+
line-height: 1.5;
14+
}
15+
16+
.highlight pre {
17+
background: transparent !important;
18+
border: none !important;
19+
margin: 0 !important;
20+
padding: 0 !important;
21+
overflow: visible;
22+
white-space: pre;
23+
}
24+
25+
/* Language-specific border colors for better identification */
26+
.highlight-python .highlight {
27+
border-left: 4px solid #3776ab;
28+
}
29+
30+
.highlight-bash .highlight {
31+
border-left: 4px solid #4EAA25;
32+
}
33+
34+
.highlight-text .highlight {
35+
border-left: 4px solid #6c757d;
36+
background: #f8f9fa !important;
37+
color: #495057;
38+
}
39+
40+
.highlight-json .highlight {
41+
border-left: 4px solid #ff6b35;
42+
}
43+
44+
/* Enhanced Python syntax highlighting */
45+
.highlight .c { color: #6a737d; font-style: italic; } /* Comment */
46+
.highlight .k { color: #d73a49; font-weight: bold; } /* Keyword */
47+
.highlight .kn { color: #d73a49; } /* Keyword.Namespace */
48+
.highlight .kp { color: #005cc5; } /* Keyword.Pseudo */
49+
.highlight .kr { color: #d73a49; } /* Keyword.Reserved */
50+
.highlight .kt { color: #d73a49; } /* Keyword.Type */
51+
.highlight .n { color: #24292e; } /* Name */
52+
.highlight .na { color: #6f42c1; } /* Name.Attribute */
53+
.highlight .nb { color: #005cc5; } /* Name.Builtin */
54+
.highlight .nc { color: #6f42c1; font-weight: bold; } /* Name.Class */
55+
.highlight .nd { color: #6f42c1; } /* Name.Decorator */
56+
.highlight .nf { color: #6f42c1; font-weight: bold; } /* Name.Function */
57+
.highlight .nn { color: #6f42c1; } /* Name.Namespace */
58+
.highlight .nt { color: #22863a; } /* Name.Tag */
59+
.highlight .nv { color: #e36209; } /* Name.Variable */
60+
.highlight .o { color: #d73a49; } /* Operator */
61+
.highlight .s { color: #032f62; } /* String */
62+
.highlight .s1 { color: #032f62; } /* String.Single */
63+
.highlight .s2 { color: #032f62; } /* String.Double */
64+
.highlight .sb { color: #032f62; } /* String.Backtick */
65+
.highlight .sc { color: #032f62; } /* String.Char */
66+
.highlight .sd { color: #032f62; font-style: italic; } /* String.Doc */
67+
.highlight .se { color: #032f62; font-weight: bold; } /* String.Escape */
68+
.highlight .sh { color: #032f62; } /* String.Heredoc */
69+
.highlight .si { color: #032f62; } /* String.Interpol */
70+
.highlight .sx { color: #032f62; } /* String.Other */
71+
.highlight .sr { color: #032f62; } /* String.Regex */
72+
.highlight .ss { color: #032f62; } /* String.Symbol */
73+
.highlight .m { color: #005cc5; } /* Number */
74+
.highlight .mf { color: #005cc5; } /* Number.Float */
75+
.highlight .mi { color: #005cc5; } /* Number.Integer */
76+
.highlight .mo { color: #005cc5; } /* Number.Oct */
77+
.highlight .mh { color: #005cc5; } /* Number.Hex */
78+
79+
/* Bash/Shell specific highlighting */
80+
.highlight-bash .gp { color: #6a737d; font-weight: bold; } /* Generic.Prompt */
81+
.highlight-bash .go { color: #6a737d; } /* Generic.Output */
82+
83+
/* JSON specific highlighting */
84+
.highlight-json .p { color: #24292e; } /* Punctuation */
85+
86+
/* Copy button styling improvements */
87+
.copybtn {
88+
background: #6c757d !important;
89+
color: white !important;
90+
border: none;
91+
border-radius: 3px;
92+
font-size: 0.75em;
93+
padding: 0.25em 0.5em;
94+
opacity: 0.7;
95+
transition: opacity 0.2s ease;
96+
}
97+
98+
.copybtn:hover {
99+
opacity: 1;
100+
background: #5a6268 !important;
101+
}
102+
103+
/* Code block captions */
104+
.code-block-caption {
105+
background: #e9ecef;
106+
padding: 0.5em 1em;
107+
margin: 1em 0 0 0;
108+
border-radius: 6px 6px 0 0;
109+
font-weight: 600;
110+
font-size: 0.875em;
111+
border: 1px solid #dee2e6;
112+
border-bottom: none;
113+
color: #495057;
114+
}
115+
116+
.code-block-caption + .highlight {
117+
margin-top: 0;
118+
border-radius: 0 0 6px 6px;
119+
}
120+
121+
/* Dark theme support */
122+
@media (prefers-color-scheme: dark) {
123+
.highlight {
124+
background: #0d1117 !important;
125+
color: #e6edf3;
126+
border-color: #30363d;
127+
}
128+
129+
.highlight .c { color: #8b949e; } /* Comment */
130+
.highlight .k { color: #ff7b72; } /* Keyword */
131+
.highlight .kn { color: #ff7b72; } /* Keyword.Namespace */
132+
.highlight .kp { color: #79c0ff; } /* Keyword.Pseudo */
133+
.highlight .kr { color: #ff7b72; } /* Keyword.Reserved */
134+
.highlight .kt { color: #ff7b72; } /* Keyword.Type */
135+
.highlight .n { color: #e6edf3; } /* Name */
136+
.highlight .na { color: #d2a8ff; } /* Name.Attribute */
137+
.highlight .nb { color: #79c0ff; } /* Name.Builtin */
138+
.highlight .nc { color: #d2a8ff; } /* Name.Class */
139+
.highlight .nd { color: #d2a8ff; } /* Name.Decorator */
140+
.highlight .nf { color: #d2a8ff; } /* Name.Function */
141+
.highlight .nn { color: #d2a8ff; } /* Name.Namespace */
142+
.highlight .nt { color: #7ee787; } /* Name.Tag */
143+
.highlight .nv { color: #ffa657; } /* Name.Variable */
144+
.highlight .o { color: #ff7b72; } /* Operator */
145+
.highlight .s { color: #a5d6ff; } /* String */
146+
.highlight .s1 { color: #a5d6ff; } /* String.Single */
147+
.highlight .s2 { color: #a5d6ff; } /* String.Double */
148+
.highlight .m { color: #79c0ff; } /* Number */
149+
150+
.code-block-caption {
151+
background: #21262d;
152+
color: #e6edf3;
153+
border-color: #30363d;
154+
}
155+
}
156+
157+
/* RTD theme specific overrides */
158+
.rst-content .highlight {
159+
background: #f8f9fa !important;
160+
}
161+
162+
.rst-content .highlight pre {
163+
background: transparent !important;
164+
color: inherit !important;
165+
}
166+
167+
/* Ensure consistent font rendering */
168+
.highlight, .highlight pre, .highlight code {
169+
font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, 'Courier New', monospace !important;
170+
}
171+
172+
/* Line number styling if enabled */
173+
.highlight .linenos {
174+
background: rgba(0, 0, 0, 0.05);
175+
border-right: 1px solid #ddd;
176+
color: #999;
177+
padding-right: 0.5em;
178+
margin-right: 0.5em;
179+
}
180+
181+
/* Responsive design for smaller screens */
182+
@media (max-width: 768px) {
183+
.highlight {
184+
font-size: 0.8em;
185+
padding: 0.75em;
186+
}
187+
}

‎docs/source/conf.py‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,18 +26,22 @@
2626
templates_path = ["_templates"]
2727
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
2828
source_suffix = ".rst"
29-
pygments_style = "default"
29+
pygments_style = "github-dark"
3030

3131
# -- Syntax highlighting configuration ----------------------------------------
3232
# Ensure consistent syntax highlighting across all code blocks
3333
highlight_language = "python"
3434
highlight_options = {
35-
'default': {'stripall': False},
36-
'python': {'stripall': False},
37-
'bash': {'stripall': False},
38-
'text': {'stripall': False},
35+
'default': {'stripnl': True, 'stripall': True},
36+
'python': {'stripnl': True, 'stripall': True},
37+
'bash': {'stripnl': True, 'stripall': True},
38+
'text': {'stripnl': False, 'stripall': False},
39+
'json': {'stripnl': True, 'stripall': True},
3940
}
4041

42+
# Enable dark theme support for better contrast
43+
pygments_dark_style = "github-dark"
44+
4145
# -- Copy button configuration -----------------------------------------------
4246
# Configure sphinx-copybutton to skip prompts and output
4347
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
@@ -49,6 +53,12 @@
4953
html_theme = "sphinx_rtd_theme"
5054
html_static_path = ["_static"]
5155

56+
# Include custom CSS files for enhanced syntax highlighting
57+
html_css_files = [
58+
'custom.css',
59+
'syntax_highlighting.css',
60+
]
61+
5262
html_theme_options = {
5363
"collapse_navigation": True,
5464
"navigation_depth" : 2,

0 commit comments

Comments
 (0)