Skip to content

Commit 5415a0c

Browse files
sepermanseperman
committed
updating docs
1 parent ae9433d commit 5415a0c

File tree

5 files changed

+112
-17
lines changed

5 files changed

+112
-17
lines changed

‎docs/AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
CLAUDE.md

‎docs/CLAUDE.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Docs CLAUDE.md
2+
3+
## Building Documentation
4+
5+
```bash
6+
cd docs && source ~/.venvs/deep/bin/activate && python buildme.py
7+
```
8+
9+
The build output goes to `~/Workspace/sites/blog/public/deepdiff/<version>/` (configured via `docs/.env`).
10+
To verify changes, check the generated HTML, e.g. `~/Workspace/sites/blog/public/deepdiff/8.7.0/faq.html`.
11+
12+
The Sphinx doctree cache is stored in `/tmp/sphinx_doctree`. The build script clears it each run. If you get permission errors on that directory, ask the user to `rm -rf /tmp/sphinx_doctree` first.
13+
14+
## Theme
15+
16+
Uses the **Furo** Sphinx theme. Key customizations:
17+
18+
- **Font**: Open Sans, loaded via `_static/custom.css` and set in `conf.py` via `light_css_variables` / `dark_css_variables`
19+
- **Footer**: Custom `_templates/page.html` overrides the default footer to remove Sphinx/Furo credit while keeping the copyright notice
20+
- **GA4**: Google Analytics tag (`G-KVVHD37BKD`) is injected via `_templates/page.html` in the `extrahead` block
21+
- **Pygments**: Uses Furo's default syntax highlighting (no explicit `pygments_style` set)
22+
23+
## File Structure
24+
25+
- `conf.py` — Sphinx configuration
26+
- `buildme.py` — Build script (reads `.env` for `BUILD_PATH` and `DOC_VERSION`)
27+
- `_templates/page.html` — Extends `furo/page.html` for GA4 and custom footer
28+
- `_static/custom.css` — Loads Open Sans font from Google Fonts

‎docs/_static/custom.css‎

Lines changed: 1 addition & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1 @@
1-
/* latin-ext */
2-
@font-face {
3-
font-family: 'Open Sans';
4-
font-style: normal;
5-
font-weight: 400;
6-
src: local('Open Sans Regular'), local('OpenSans-Regular'), url(https://fonts.gstatic.com/s/opensans/v17/mem8YaGs126MiZpBA-UFW50bbck.woff2) format('woff2');
7-
unicode-range: U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF;
8-
}
9-
/* latin */
10-
@font-face {
11-
font-family: 'Open Sans';
12-
font-style: normal;
13-
font-weight: 400;
14-
src: local('Open Sans Regular'), local('OpenSans-Regular'), url(https://fonts.gstatic.com/s/opensans/v17/mem8YaGs126MiZpBA-UFVZ0b.woff2) format('woff2');
15-
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
16-
}
1+
@import url('https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap');

‎docs/_templates/page.html‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
{% extends "furo/page.html" %}
2+
3+
{% block extrahead %}
4+
<!-- Google tag (gtag.js) -->
5+
<script async src="https://www.googletagmanager.com/gtag/js?id=G-KVVHD37BKD"></script>
6+
<script>
7+
window.dataLayer = window.dataLayer || [];
8+
function gtag(){dataLayer.push(arguments);}
9+
gtag('js', new Date());
10+
gtag('config', 'G-KVVHD37BKD');
11+
</script>
12+
{% endblock %}
13+
14+
{% block footer %}
15+
<div class="related-pages">
16+
{% if next -%}
17+
<a class="next-page" href="{{ next.link }}">
18+
<div class="page-info">
19+
<div class="context">
20+
<span>{{ _("Next") }}</span>
21+
</div>
22+
<div class="title">{{ next.title }}</div>
23+
</div>
24+
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
25+
</a>
26+
{%- endif %}
27+
{% if prev -%}
28+
<a class="prev-page" href="{{ prev.link }}">
29+
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
30+
<div class="page-info">
31+
<div class="context">
32+
<span>{{ _("Previous") }}</span>
33+
</div>
34+
{% if prev.link == pathto(master_doc) %}
35+
<div class="title">{{ _("Home") }}</div>
36+
{% else %}
37+
<div class="title">{{ prev.title }}</div>
38+
{% endif %}
39+
</div>
40+
</a>
41+
{%- endif %}
42+
</div>
43+
<div class="bottom-of-page">
44+
<div class="left-details">
45+
{%- if show_copyright %}
46+
<div class="copyright">
47+
{%- if hasdoc('copyright') %}
48+
{% trans path=pathto('copyright'), copyright=copyright|e -%}
49+
<a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
50+
{%- endtrans %}
51+
{%- else %}
52+
{% trans copyright=copyright|e -%}
53+
Copyright &#169; {{ copyright }}
54+
{%- endtrans %}
55+
{%- endif %}
56+
</div>
57+
{%- endif %}
58+
</div>
59+
<div class="right-details">
60+
{% if theme_footer_icons -%}
61+
<div class="icons">
62+
{% for icon_dict in theme_footer_icons -%}
63+
<a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
64+
{{- icon_dict.html -}}
65+
</a>
66+
{% endfor %}
67+
</div>
68+
{%- endif %}
69+
</div>
70+
</div>
71+
{% endblock %}

‎docs/conf.py‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,8 @@
105105
#show_authors = False
106106

107107
# The name of the Pygments (syntax highlighting) style to use.
108-
pygments_style = 'sphinx'
108+
# Let Furo use its default pygments styles (light + dark mode aware)
109+
# pygments_style = 'sphinx'
109110

110111
# A list of ignored prefixes for module index sorting.
111112
#modindex_common_prefix = []
@@ -144,6 +145,14 @@
144145
'source_repository': 'https://github.com/seperman/deepdiff',
145146
'source_branch': 'master',
146147
'source_directory': 'docs/',
148+
'light_css_variables': {
149+
'font-stack': "'Open Sans', sans-serif",
150+
'font-stack--headings': "'Open Sans', sans-serif",
151+
},
152+
'dark_css_variables': {
153+
'font-stack': "'Open Sans', sans-serif",
154+
'font-stack--headings': "'Open Sans', sans-serif",
155+
},
147156
}
148157

149158
# Add any paths that contain custom themes here, relative to this directory.
@@ -169,6 +178,7 @@
169178
# relative to this directory. They are copied after the builtin static files,
170179
# so a file named "default.css" will overwrite the builtin "default.css".
171180
html_static_path = ['_static']
181+
html_css_files = ['custom.css']
172182

173183
# Add any extra paths that contain custom files (such as robots.txt or
174184
# .htaccess) here, relative to this directory. These files are copied

0 commit comments

Comments
 (0)