Skip to content

Commit 86f5f55

Browse files
gvwilsongvwilson
committed
feat: modify to work with mkdocs-material as well
1. Move configuration `mkdocs.yml` to `mkdocs-vanilla.yml`. 1. Move logic to set `details` from `theme/main.jinja` to `theme/attribute.jinja` where it is actually used. 1. Create new `mkdocs-material.yml` configuration file with mkdocs-material settings. 1. Change configuration to load overrides from `overrides` directory. 1. Copy template files *without* `main.jinja` to `overrides` directory. 1. Modify `Makefile` to build `mkdocs-vanilla` (our own) or `mkdocs-material`.
1 parent 2ac2664 commit 86f5f55

10 files changed

+278
-24
lines changed

‎Makefile

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,13 @@ SCHEMA=test/plot-schema.json
66
REF_PAGES=ref_pages
77
THEME=theme
88

9-
## site: rebuild with MkDocs
10-
site:
11-
mkdocs build
9+
## material: rebuild with MkDocs using mkdocs-material and 'overrides' directory
10+
material:
11+
mkdocs build -f mkdocs-material.yml
12+
13+
## vanilla: rebuild with MkDocs using 'theme' directory (our own)
14+
vanilla:
15+
mkdocs build -f mkdocs-vanilla.yml
1216

1317
## pages: make all the pages
1418
pages:

‎mkdocs-material.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
site_name: Plotly Libraries
2+
site_description: Documentation for Plotly libraries
3+
site_url: https://example.com
4+
copyright: Plotly Inc.
5+
6+
docs_dir: ref_pages
7+
site_dir: docs
8+
theme:
9+
name: material
10+
custom_dir: overrides
11+
12+
plugins:
13+
- exclude:
14+
regex:
15+
- '.*\.jinja'
16+
- mkdocs-data-loader:
17+
dir: dist
18+
key: data

‎mkdocs.yml renamed to ‎mkdocs-vanilla.yml

File renamed without changes.

‎overrides/attribute.jinja

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{% extends "base.html" %}
2+
{% block content %}
3+
{{ super() }}
4+
{# reach into the schema data and pull out details #}
5+
{% if "full_name" not in page.meta %}
6+
{# trace #}
7+
{% set details=page.meta %}
8+
{% else %}
9+
{% set temp_key=page.meta.name.split(".")[-1] %}
10+
{% set temp=config["data"]["plot-schema"]["layout"]["layoutAttributes"][temp_key] %}
11+
{% if "_isSubplotObj" in temp %}
12+
{# subplot #}
13+
{% set details=temp %}
14+
{% else %}
15+
{# everything that isn't trace or subplot #}
16+
{% set details=temp["items"].values() | first %}
17+
{% endif %}
18+
{% endif %}
19+
<h2>JavaScript Figure Reference: <code>{{page.full_name}}</code></h2>
20+
{% with toplevel=true, parentlink=page.layout, block=page.layout, parentpath=page.layout, attribute=details %}
21+
{% include "block.jinja" %}
22+
{% endwith %}
23+
{% endblock %}

‎overrides/block.jinja

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
{#
2+
Document a chunk of the API by iterating through plot schema JSON.
3+
Note: this template may call itself recursively for structured objects.
4+
- toplevel (bool): is this a top-level documentation entry?
5+
- attribute (JSON): data to expand as documentation
6+
- keys_to_ignore (set): keys that are *not* to be documented
7+
- parentlink: slug for parent of this entry
8+
- block: section or "nested" for nested invocations
9+
- parentpath: possibly redundant?
10+
- attribute: dictionary with details to document
11+
- page: information pulled from YAML header of page
12+
- name: name of top-level entry (e.g., "annotations")
13+
- full_name (unused): qualified name (e.g., "layout.annotations")
14+
- description (unused): one-sentence description of this item
15+
- permalink (unused): path to output page
16+
#}
17+
{% set id=[parentlink, "-", page.name] | join %}
18+
{% if toplevel %}<a class="attribute-name" id="{{id}}" href="#{{parentlink}}-{{page.name}}">{{page.name}}</a>{% endif %}
19+
<br>
20+
<em>Parent:</em> <code>{{parentpath | replace('-', '.')}}</code>
21+
<ul>
22+
{% for key, obj in attribute.items() %}
23+
{% if key not in keys_to_ignore %}
24+
<li><code>{{key}}</code>
25+
{% if obj is string %}
26+
{{obj}}<!-- FIXME: backtick -->
27+
{% elif obj.valType %}
28+
<br>
29+
{% if obj.valType == "enumerated" or obj.valType.values %}
30+
<em>Type:</em>
31+
{{ obj.valType }}
32+
{% if obj["arrayOk"] %} or array of {{ obj.valType }}s{% endif %}
33+
, one of (
34+
{% for value in obj["values"] %}
35+
{% if value != false and value != true %}<code>"{{value}}"</code>{% else %}<code>{{value}}</code>{% endif %}
36+
{% if not loop.last %}|{% endif %}
37+
{% endfor %}
38+
)
39+
40+
{% elif obj.valType == "number" or obj.valType == "integer" %}
41+
{% if obj["min"] and obj["max"] %}
42+
<em>Type:</em> {{ obj.valType }}{% if obj["arrayOk"] %} or array of {{ obj.valType }}s{% endif %} between or equal to {{obj["min"]}} and {{obj["max"]}}
43+
{% elif obj["min"] %}
44+
<em>Type:</em> {{ obj.valType }}{% if obj["arrayOk"] %} or array of {{ obj.valType }}s{% endif %} greater than or equal to {{obj["min"]}}
45+
{% elif obj["max"] %}
46+
<em>Type:</em> {{ obj.valType }}{% if obj["arrayOk"] %} or array of {{ obj.valType }}s{% endif %} less than or equal to {{obj["min"]}}
47+
{% else %}
48+
<em>Type:</em> {{ obj.valType }}{% if obj["arrayOk"] %} or array of {{ obj.valType }}s{% endif %}
49+
{% endif %}
50+
51+
{% elif obj.valType == "boolean" %}
52+
<em>Type:</em> {{ obj.valType }}{% if obj["arrayOk"] %} or array of {{ obj.valType }}s{% endif %}
53+
54+
{% elif obj.valType == "flaglist" %}
55+
<em>Type:</em> {{ obj.valType }} string.
56+
57+
Any combination of
58+
{% for value in obj["flags"] %}
59+
{% if value != false and value != true %}
60+
<code>"{{value}}"</code>
61+
{% else %}
62+
<code>{{value}}</code>
63+
{% endif %}
64+
{% if not loop.last %}, {% endif %}
65+
{% endfor %}
66+
joined with a <code>"+"</code>
67+
68+
{% if obj["extras"] %}
69+
OR
70+
{% for value in obj["extras"] %}
71+
{% if value != false and value != true %}
72+
<code>"{{value}}"</code>
73+
{% else %}
74+
<code>{{value}}</code>
75+
{% endif %}
76+
{% if not loop.last %} or {% endif %}
77+
{% endfor %}.
78+
{% endif %}
79+
80+
<br>
81+
<em>Examples:</em>
82+
<code>"{{obj["flags"][0]}}"</code>,
83+
<code>"{{obj["flags"][1]}}"</code>,
84+
<code>"{{obj["flags"][0]}}+{{obj["flags"][1]}}"</code>
85+
{% if obj["flags"][2] %}, <code>"{{obj["flags"][0]}}+{{obj["flags"][1]}}+{{obj["flags"][2]}}"</code>{% endif %}
86+
{% if obj["extras"] %}, <code>"{{obj["extras"][0]}}"</code>{% endif %}
87+
88+
{% elif obj.valType == "data_array" %}
89+
<em>Type:</em> {{obj.valType}}
90+
91+
{% elif obj.valType == "info_array" %}
92+
<em>Type:</em> {array}
93+
94+
{% elif obj.valType == "color" %}
95+
<em>Type:</em> {{ obj.valType }}{% if obj["arrayOk"] %} or array of {{ obj.valType }}s{% endif %}
96+
97+
{% elif obj.valType == "any" %}
98+
<em>Type:</em> number or categorical coordinate string
99+
100+
{% elif obj.valType == "string" %}
101+
<em>Type:</em> string{% if obj["arrayOk"] %} or array of strings{% endif %}
102+
103+
{% else %}
104+
<em>Type:</em> {{ obj.valType }}
105+
{% endif %}
106+
107+
{% if obj["role"] == "object" %}
108+
{% if obj["items"] %}
109+
<em>Type:</em> array of objects
110+
{% else %}
111+
<em>Type:</em> object
112+
{% endif %}
113+
{% endif %}
114+
{% endif %}
115+
116+
{% if obj["dflt"] %}
117+
{% if obj["valType"] == "flaglist" %}
118+
<br><em>Default:</em> <code>"{{ obj["dflt"] }}"</code>
119+
{% else %}
120+
<br><em>Default:</em>
121+
<code>
122+
{%- if obj["dflt"] == "" -%}
123+
""
124+
{%- elif obj["valType"] == "colorscale" -%}
125+
[{% for d in obj["dflt"] %}[{{d | join(", ")}}], {% endfor %}]
126+
{%- elif obj["valType"] == "info_array" or obj["valType"] == "colorlist" -%}
127+
[{{obj["dflt"] | join(", ")}}]
128+
{%- elif obj["valType"] == "string" or obj["valType"] == "color" or obj["dflt"] == "auto" -%}
129+
"{{ obj["dflt"] }}"
130+
{%- elif obj["valType"] == "enumerated" and obj["dflt"] != true and obj["dflt"] != false -%}
131+
"{{ obj["dflt"] }}"
132+
{%- else -%}
133+
{{obj["dflt"]}}
134+
{%- endif %}
135+
</code>
136+
{% endif %}
137+
{% endif %}
138+
139+
{% if obj["items"] and obj["valType"] != "info_array" %}
140+
141+
<br><em>Type:</em> array of object where
142+
each object has one or more of the keys listed below.
143+
{% if page.name == "annotations" %}
144+
{% if not obj["description"] %}
145+
<br>An annotation is a text element that can be placed anywhere in the plot. It can be positioned with respect to relative coordinates in the plot or with respect to the actual data coordinates of the graph. Annotations can be shown with or without an arrow.
146+
{% endif %}
147+
{% endif %}
148+
{% elif obj["role"] == "object" %}
149+
<br><em>Type:</em> object containing one or more of the keys listed below.
150+
{% endif %}
151+
152+
{% if obj["description"] and obj["description"]!= "" %}
153+
<br>
154+
{{ obj["description"] | replace("*", '"') | escape}}<!-- FIXME: backtick -->
155+
{% endif %}
156+
157+
{% if obj["role"] == "object" %}
158+
{% set localparentlink=[parentlink, "-", page.name] | join %}
159+
{% set localparentpath=[parentpath, "-", page.name] | join %}
160+
{% with toplevel=False, parentlink=localparentlink, block="nested", parentpath=localparentpath, attribute=obj %}
161+
{% include "block.jinja" %}
162+
{% endwith %}
163+
{% endif %}
164+
165+
</li>
166+
{% endif %}
167+
{% endfor %}
168+
</ul>

‎overrides/global.jinja

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{% extends "base.html" %}
2+
{% block content %}
3+
{{ super() }}
4+
5+
<h2>JavaScript Figure Reference: <code>layout</code></h2>
6+
{% with parentlink=page.layout, block=page.layout, parentpath=page.layout, mustmatch=page.global, attribute=config["data"]["plot-schema"]["layout"]["layoutAttributes"] %}
7+
{% include "block.jinja" %}
8+
{% endwith %}
9+
{% for trace in config["data"]["plot-schema"]["traces"] %}
10+
{% if trace[1].layoutAttributes %}
11+
{% with parentlink=page.layout, block=page.layout, parentpath=page.layout, attribute=trace[1].layoutAttributes %}
12+
{% include "block.jinja" %}
13+
{% endwith %}
14+
{% endif %}
15+
{% endfor %}
16+
{% endblock %}

‎overrides/trace.jinja

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{% extends "base.html" %}
2+
{% block content %}
3+
{{ super() }}
4+
5+
<h2>JavaScript Figure Reference: <code>page.trace</code> Traces</h2>
6+
{% with trace_name=page.meta.trace, trace_data=config["data"]["plot-schema"].traces[page.meta.trace] %}
7+
<div class="description">
8+
A <code>{{trace_name}}</code> trace is an object with the key <code>"type"</code> equal to <code>"{{trace_data.attributes.type}}"</code>
9+
(i.e. <code>{"type": "{{trace_data.attributes.type}}"}</code>) and any of the keys listed below.
10+
<br>
11+
{{trace_data.meta.description}}{# FIXME: backtick #}
12+
</div>
13+
14+
{% set localparentlink=trace_name %}
15+
{% set localparentpath="FIXME" %}
16+
{% set attribute=trace_data.attributes %}
17+
{% with parentlink=localparentlink, block="data", parentpath=localparentpath %}
18+
{% include "block.jinja" %}
19+
{% endwith %}
20+
21+
{% endwith %}
22+
{% endblock %}
23+

‎requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,6 @@ html5validator
33
jinja2
44
mkdocs
55
mkdocs-exclude
6+
mkdocs-material
67
python-frontmatter
78
ruff

‎theme/attribute.jinja

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,25 @@
11
{% extends "main.jinja" %}
22
{% block content %}
3-
<h2>JavaScript Figure Reference: <code>{{page.full_name}}</code></h2>
4-
{% with toplevel=true, parentlink=page.layout, block=page.layout, parentpath=page.layout, attribute=details %}
5-
{% include "block.jinja" %}
6-
{% endwith %}
3+
4+
{# reach into the schema data and pull out details #}
5+
{% if "full_name" not in page.meta %}
6+
{# trace #}
7+
{% set details=page.meta %}
8+
{% else %}
9+
{% set temp_key=page.meta.name.split(".")[-1] %}
10+
{% set temp=config["data"]["plot-schema"]["layout"]["layoutAttributes"][temp_key] %}
11+
{% if "_isSubplotObj" in temp %}
12+
{# subplot #}
13+
{% set details=temp %}
14+
{% else %}
15+
{# everything that isn't trace or subplot #}
16+
{% set details=temp["items"].values() | first %}
17+
{% endif %}
18+
{% endif %}
19+
20+
<h2>JavaScript Figure Reference: <code>{{page.full_name}}</code></h2>
21+
{% with toplevel=true, parentlink=page.layout, block=page.layout, parentpath=page.layout, attribute=details %}
22+
{% include "block.jinja" %}
23+
{% endwith %}
24+
725
{% endblock %}

‎theme/main.jinja

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -7,23 +7,6 @@
77
<body>
88
<main>
99
{% block page_title %}<h1>{{page["title"]}}</h1>{% endblock %}
10-
11-
{# reach into the schema data and pull out details #}
12-
{% if "full_name" not in page.meta %}
13-
{# trace #}
14-
{% set details=page.meta %}
15-
{% else %}
16-
{% set temp_key=page.meta.name.split(".")[-1] %}
17-
{% set temp=config["data"]["plot-schema"]["layout"]["layoutAttributes"][temp_key] %}
18-
{% if "_isSubplotObj" in temp %}
19-
{# subplot #}
20-
{% set details=temp %}
21-
{% else %}
22-
{# everything that isn't trace or subplot #}
23-
{% set details=temp["items"].values() | first %}
24-
{% endif %}
25-
{% endif %}
26-
2710
{% block content %}{% endblock %}
2811
</main>
2912
</body>

0 commit comments

Comments
 (0)