Skip to content

Commit 5861664

Browse files
carl-adams-planetcarl-adams-planet
authored
update docs to be selve contained and identify their own version. (#19)
1 parent a9df384 commit 5861664

File tree

5 files changed

+155
-10
lines changed

5 files changed

+155
-10
lines changed

‎docs/custom_theme/partials/header.html

+131
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
<!--
2+
Planet Theme customization.
3+
4+
Source: https://github.com/squidfunk/mkdocs-material/blob/9.6.12/src/templates/partials/header.html
5+
6+
Customizations:
7+
- Add version to title so docs can be self-contained, and do not depend on
8+
external framing to understand what version they refer to.
9+
-->
10+
<!--
11+
Copyright (c) 2016-2025 Martin Donath <[email protected]>
12+
13+
Permission is hereby granted, free of charge, to any person obtaining a copy
14+
of this software and associated documentation files (the "Software"), to
15+
deal in the Software without restriction, including without limitation the
16+
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
17+
sell copies of the Software, and to permit persons to whom the Software is
18+
furnished to do so, subject to the following conditions:
19+
20+
The above copyright notice and this permission notice shall be included in
21+
all copies or substantial portions of the Software.
22+
23+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25+
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
26+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
28+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
29+
IN THE SOFTWARE.
30+
-->
31+
32+
<!-- Determine classes -->
33+
{% set class = "md-header" %}
34+
{% if "navigation.tabs.sticky" in features %}
35+
{% set class = class ~ " md-header--shadow md-header--lifted" %}
36+
{% elif "navigation.tabs" not in features %}
37+
{% set class = class ~ " md-header--shadow" %}
38+
{% endif %}
39+
40+
<!-- Header -->
41+
<header class="{{ class }}" data-md-component="header">
42+
<nav
43+
class="md-header__inner md-grid"
44+
aria-label="{{ lang.t('header') }}"
45+
>
46+
47+
<!-- Link to home -->
48+
<a
49+
href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}"
50+
title="{{ config.site_name | e }} ({{ config.extra.site_version }})"
51+
class="md-header__button md-logo"
52+
aria-label="{{ config.site_name }} ({{ config.extra.site_version }})"
53+
data-md-component="logo"
54+
>
55+
{% include "partials/logo.html" %}
56+
</a>
57+
58+
<!-- Button to open drawer -->
59+
<label class="md-header__button md-icon" for="__drawer">
60+
{% set icon = config.theme.icon.menu or "material/menu" %}
61+
{% include ".icons/" ~ icon ~ ".svg" %}
62+
</label>
63+
64+
<!-- Header title -->
65+
<div class="md-header__title" data-md-component="header-title">
66+
<div class="md-header__ellipsis">
67+
<div class="md-header__topic">
68+
<span class="md-ellipsis">
69+
{{ config.site_name }} <span style="font-size: smaller">({{ config.extra.site_version }})</span>
70+
</span>
71+
</div>
72+
<div class="md-header__topic" data-md-component="header-topic">
73+
<span class="md-ellipsis">
74+
{% if page.meta and page.meta.title %}
75+
{{ page.meta.title }}
76+
{% else %}
77+
{{ page.title }}
78+
{% endif %}
79+
</span>
80+
</div>
81+
</div>
82+
</div>
83+
84+
<!-- Color palette toggle -->
85+
{% if config.theme.palette %}
86+
{% if not config.theme.palette is mapping %}
87+
{% include "partials/palette.html" %}
88+
{% endif %}
89+
{% endif %}
90+
91+
<!-- User preference: color palette -->
92+
{% if not config.theme.palette is mapping %}
93+
{% include "partials/javascripts/palette.html" %}
94+
{% endif %}
95+
96+
<!-- Site language selector -->
97+
{% if config.extra.alternate %}
98+
{% include "partials/alternate.html" %}
99+
{% endif %}
100+
101+
<!-- Button to open search modal -->
102+
{% if "material/search" in config.plugins %}
103+
{% set search = config.plugins["material/search"] | attr("config") %}
104+
105+
<!-- Check if search is actually enabled - see https://t.ly/DT_0V -->
106+
{% if search.enabled %}
107+
<label class="md-header__button md-icon" for="__search">
108+
{% set icon = config.theme.icon.search or "material/magnify" %}
109+
{% include ".icons/" ~ icon ~ ".svg" %}
110+
</label>
111+
112+
<!-- Search interface -->
113+
{% include "partials/search.html" %}
114+
{% endif %}
115+
{% endif %}
116+
117+
<!-- Repository information -->
118+
{% if config.repo_url %}
119+
<div class="md-header__source">
120+
{% include "partials/source.html" %}
121+
</div>
122+
{% endif %}
123+
</nav>
124+
125+
<!-- Navigation tabs (sticky) -->
126+
{% if "navigation.tabs.sticky" in features %}
127+
{% if "navigation.tabs" in features %}
128+
{% include "partials/tabs.html" %}
129+
{% endif %}
130+
{% endif %}
131+
</header>

‎docs/hooks/mkdocs_hooks.py

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
import importlib.metadata
2+
3+
4+
def on_config(config):
5+
"""
6+
This is for injecting the package version into mkdocs
7+
config so it can be used in templates.
8+
"""
9+
config["extra"]["site_version"] = importlib.metadata.version("planet-auth")
10+
return config

‎docs/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Planet Auth Utility Library
1+
# Planet Auth Utility Library <br/> {{ config.extra.site_version }}
22

33
## Overview
44
The Planet Auth Library provides generic authentication utilities for clients

‎mkdocs.yml

+12-8
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ theme:
1111
name: 'material'
1212
logo: img/logo-white.svg
1313
favicon: img/logo-color.svg
14-
# custom_dir: 'docs/custom_theme/'
14+
custom_dir: 'docs/custom_theme/'
1515
features:
1616
- content.code.copy
1717
- navigation.tabs
@@ -38,6 +38,10 @@ theme:
3838
icon: octicons/sun-24
3939
name: Switch to light mode
4040

41+
42+
hooks:
43+
- docs/hooks/mkdocs_hooks.py
44+
4145
plugins:
4246
- search:
4347
- macros:
@@ -66,13 +70,13 @@ repo_url: https://github.com/planetlabs/planet-auth-python
6670
#edit_uri: ""
6771

6872
nav:
69-
- Introduction: 'index.md'
70-
- CLI Reference:
71-
- plauth: 'cli-plauth.md'
72-
- Configuration: 'configuration.md'
73-
- API Reference: 'api.md'
74-
- Examples: 'examples.md'
75-
- Changelog: 'changelog.md'
73+
- Introduction: 'index.md'
74+
- CLI Reference:
75+
- plauth: 'cli-plauth.md'
76+
- Configuration: 'configuration.md'
77+
- API Reference: 'api.md'
78+
- Examples: 'examples.md'
79+
- Changelog: 'changelog.md'
7680

7781
markdown_extensions:
7882
- pymdownx.highlight

‎pyproject.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ docs = [
4343
# https://github.com/mkdocstrings/mkdocstrings/discussions/743
4444
"mkdocstrings[python] == 0.28.3",
4545
"mkdocs-click",
46-
"mkdocs-material",
46+
"mkdocs-material == 9.6.12", # Upgrades may interact with docs/custom_theme
4747
"mkdocs-macros-plugin"
4848
]
4949
examples = [

0 commit comments

Comments
 (0)