Skip to content

Refactor make_docs.py #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 16, 2023
Merged

Refactor make_docs.py #76

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a873a86
update deps
janosh Apr 14, 2023
f1ad24f
move make_docs.py to site/ and add notebook to HTML conversion
janosh Apr 14, 2023
b42d0d3
use kwargs.setdefault instead of if statement
janosh Apr 14, 2023
6815e6c
fix npm ERR! Missing script: "make-html-examples"
janosh Apr 14, 2023
64bc608
fix AssertionError: assert 0.4 == 0.87
janosh Apr 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .github/workflows/gh-pages.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,4 @@ jobs:
working-directory: site
pre-build: |
pip install '..[gh-pages]'
npm run make-html-examples
python ../assets/make_api_docs.py
python ../site/make_docs.py
6 changes: 3 additions & 3 deletions .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ default_install_hook_types: [pre-commit, commit-msg]

repos:
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: v0.0.260
rev: v0.0.261
hooks:
- id: ruff
args: [--fix]
Expand All @@ -18,7 +18,7 @@ repos:
- id: black-jupyter

- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.1.1
rev: v1.2.0
hooks:
- id: mypy
additional_dependencies: [types-requests]
Expand Down Expand Up @@ -49,7 +49,7 @@ repos:
args: [--ignore-words-list, "hist,mape"]

- repo: https://github.com/nbQA-dev/nbQA
rev: 1.6.4
rev: 1.7.0
hooks:
- id: nbqa-ruff

Expand Down
34 changes: 0 additions & 34 deletions assets/make_api_docs.py
View file
Open in desktop

This file was deleted.

97 changes: 40 additions & 57 deletions examples/mp_bimodal_e_form.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
" # Materials Project Formation Energy Distribution\n",
"# Materials Project Formation Energy Distribution\n",
"\n",
" MP has a curious bimodality in its formation energies. Considering the formation energies are the result of a carefully fitted correction scheme (see `pymatgen.entries.compatibility.MaterialsProject2020Compatibility`) that depends mainly on the composition of a compound, let's look at which elements dominate the upper and lower modes."
"MP has a curious bimodality in its formation energies. Considering the formation energies are the result of a carefully fitted correction scheme (see `pymatgen.entries.compatibility.MaterialsProject2020Compatibility`) that depends mainly on the composition of a compound, let's look at which elements dominate the upper and lower modes.\n"
]
},
{
Expand Down Expand Up @@ -41,10 +41,11 @@
]
},
{
"attachments": {},
"cell_type": "markdown",
"metadata": {},
"source": [
" Check if all of MP has a bi-modal formation energy distribution. Short answer: yes it does."
"Check if all of MP has a bi-modal formation energy distribution. Short answer: yes it does.\n"
]
},
{
Expand Down Expand Up @@ -134,62 +135,52 @@
" <td>GGA</td>\n",
" </tr>\n",
" <tr>\n",
" <th>...</th>\n",
" <td>...</td>\n",
" <td>...</td>\n",
" <td>...</td>\n",
" </tr>\n",
" <tr>\n",
" <th>mp-1198916</th>\n",
" <td>KSi2H14C4N</td>\n",
" <td>-0.284045</td>\n",
" <th>mp-1183258</th>\n",
" <td>AcTh3</td>\n",
" <td>0.132877</td>\n",
" <td>GGA</td>\n",
" </tr>\n",
" <tr>\n",
" <th>mp-1212071</th>\n",
" <td>K2UC2SeSNO8</td>\n",
" <td>-1.864080</td>\n",
" <td>GGA</td>\n",
" <th>mp-11343</th>\n",
" <td>Th</td>\n",
" <td>0.151527</td>\n",
" <td>R2SCAN</td>\n",
" </tr>\n",
" <tr>\n",
" <th>mp-1204915</th>\n",
" <td>K2SeS3O7</td>\n",
" <td>-1.393535</td>\n",
" <td>GGA</td>\n",
" <th>mp-862690</th>\n",
" <td>Ac</td>\n",
" <td>0.000000</td>\n",
" <td>R2SCAN</td>\n",
" </tr>\n",
" <tr>\n",
" <th>mp-616240</th>\n",
" <td>K2PtC4(SN)4</td>\n",
" <td>-0.121462</td>\n",
" <th>mp-1181019</th>\n",
" <td>Mo</td>\n",
" <td>0.331963</td>\n",
" <td>GGA</td>\n",
" </tr>\n",
" <tr>\n",
" <th>mp-1238493</th>\n",
" <td>MoH8N2O5F2</td>\n",
" <td>-0.810119</td>\n",
" <td>GGA+U</td>\n",
" <th>mp-1014111</th>\n",
" <td>Ni</td>\n",
" <td>0.620239</td>\n",
" <td>GGA</td>\n",
" </tr>\n",
" </tbody>\n",
"</table>\n",
"<p>154617 rows × 3 columns</p>\n",
"</div>"
],
"text/plain": [
" formula formation_energy_per_atom energy_type\n",
"material_id \n",
"mp-23155 Ar 0.000000 R2SCAN\n",
"mp-1094136 Ni 0.739852 GGA\n",
"mp-568714 Bi 1.117044 GGA\n",
"mp-1067758 Bi 0.036314 GGA\n",
"mp-10207 Np 0.447494 GGA\n",
"... ... ... ...\n",
"mp-1198916 KSi2H14C4N -0.284045 GGA\n",
"mp-1212071 K2UC2SeSNO8 -1.864080 GGA\n",
"mp-1204915 K2SeS3O7 -1.393535 GGA\n",
"mp-616240 K2PtC4(SN)4 -0.121462 GGA\n",
"mp-1238493 MoH8N2O5F2 -0.810119 GGA+U\n",
"\n",
"[154617 rows x 3 columns]"
" formula formation_energy_per_atom energy_type\n",
"material_id \n",
"mp-23155 Ar 0.000000 R2SCAN\n",
"mp-1094136 Ni 0.739852 GGA\n",
"mp-568714 Bi 1.117044 GGA\n",
"mp-1067758 Bi 0.036314 GGA\n",
"mp-10207 Np 0.447494 GGA\n",
"mp-1183258 AcTh3 0.132877 GGA\n",
"mp-11343 Th 0.151527 R2SCAN\n",
"mp-862690 Ac 0.000000 R2SCAN\n",
"mp-1181019 Mo 0.331963 GGA\n",
"mp-1014111 Ni 0.620239 GGA"
]
},
"execution_count": null,
Expand All @@ -200,22 +191,14 @@
"source": [
"df_e_form = pd.DataFrame(e_form_all_mp).set_index(\"material_id\")\n",
"df_e_form = df_e_form.rename(columns={\"formula_pretty\": \"formula\"})\n",
"df_e_form"
"df_e_form.head(10)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Stored 'df_e_form' (DataFrame)\n"
]
}
],
"outputs": [],
"source": [
"# cache MP data\n",
"# %store df_e_form\n",
Expand Down Expand Up @@ -386,7 +369,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Plot element heatmap for GGA and GGA+U entries above and below `e_form_valley`."
"Plot element heatmap for GGA and GGA+U entries above and below `e_form_valley`.\n"
]
},
{
Expand Down Expand Up @@ -430,9 +413,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
" Looks like the lower mode is mostly oxides, whereas the higher mode is more diverse also containing many nitrides, sulfides and selenides.\n",
"Looks like the lower mode is mostly oxides, whereas the higher mode is more diverse also containing many nitrides, sulfides and selenides.\n",
"\n",
" Another way to visualize this are bar charts."
"Another way to visualize this are bar charts.\n"
]
},
{
Expand Down Expand Up @@ -472,7 +455,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
" This significant lowering of oxide formation energies compared to other anions might at least partially be an artifact of too little experimental data outside oxide systems. In other words, perhaps there should be stronger corrections applied to nitrides, selenides, etc. as well but because there's insufficient experimental data to fit a robust correction scheme there, MP doesn't."
"This significant lowering of oxide formation energies compared to other anions might at least partially be an artifact of too little experimental data outside oxide systems. In other words, perhaps there should be stronger corrections applied to nitrides, selenides, etc. as well but because there's insufficient experimental data to fit a robust correction scheme there, MP doesn't.\n"
]
}
],
Expand Down
4 changes: 2 additions & 2 deletions pymatviz/ptable.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -479,8 +479,8 @@ def ptable_heatmap_plotly(
if len(cscale_range) != 2:
raise ValueError(f"{cscale_range=} should have length 2")

if color_bar is None:
color_bar = dict(orientation="h")
color_bar = color_bar or {}
color_bar.setdefault("orientation", "h")
# if elem_values is a series with a name, use it as the color bar title
if isinstance(elem_values, pd.Series) and elem_values.name:
color_bar.setdefault("title", elem_values.name)
Expand Down
9 changes: 5 additions & 4 deletions pymatviz/sunburst.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ def spacegroup_sunburst(
space group strings or numbers (from 1 - 230) or pymatgen structures.
show_counts ("value" | "percent" | False): Whether to display values below each
labels on the sunburst.
color_discrete_sequence (list[str]): A list of 7 colors, one for each crystal
system. Defaults to plotly.express.colors.qualitative.G10.
**kwargs: Additional keyword arguments passed to plotly.express.sunburst.

Returns:
Expand All @@ -44,13 +46,12 @@ def spacegroup_sunburst(
df = pd.DataFrame(series.value_counts().reset_index())
df.columns = ["spacegroup", "count"]

try:
try: # assume column contains integers as space group numbers
df["crystal_sys"] = [get_crystal_sys(x) for x in df.spacegroup]
except ValueError: # column must be space group strings
except ValueError: # column must be strings of space group symbols
df["crystal_sys"] = [SpaceGroup(x).crystal_system for x in df.spacegroup]

if "color_discrete_sequence" not in kwargs:
kwargs["color_discrete_sequence"] = px.colors.qualitative.G10
kwargs.setdefault("color_discrete_sequence", px.colors.qualitative.G10)

fig = px.sunburst(df, path=["crystal_sys", "spacegroup"], values="count", **kwargs)

Expand Down
64 changes: 64 additions & 0 deletions site/make_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
"""This script auto-generates markdown files from Python docstrings using lazydocs
and tweaks the output for
- prettier badges linking to source code on GitHub
- remove bold tags since they break inline code.

It also converts all notebooks in the examples folder to HTML and adds a
language class to the <pre> tag so that syntax highlighting works.
"""

import json
import os
import subprocess
from glob import glob


ROOT = os.path.dirname(os.path.dirname(__file__))
os.chdir(ROOT)
pkg = json.load(open("site/package.json"))
route = "site/src/routes/api"

for path in glob(f"{route}/*.md"):
os.remove(path)

subprocess.run(
f"lazydocs {pkg['name']} --output-path {route} "
f"--no-watermark --src-base-url {pkg['repository']}/blob/main",
shell=True,
)

for path in glob(f"{route}/*.md"):
markdown = open(path).read()
# remove <b> tags from generated markdown as they break inline code
markdown = markdown.replace("<b>", "").replace("</b>", "")
# improve style of badges linking to source code on GitHub
markdown = markdown.replace(
'src="https://img.shields.io/badge/-source-cccccc?style=flat-square"',
'src="https://img.shields.io/badge/source-blue?style=flat" alt="source link"',
)
open(path, "w").write(markdown)


# --- Notebook to HTML conversion ---
pattern = "examples/*.ipynb"
notebooks = glob(pattern)
if len(notebooks) == 0:
raise FileNotFoundError(f"no notebooks found matching {pattern!r}")

cmd = f"jupyter nbconvert --to html {pattern} --no-prompt --template basic"
subprocess.run(cmd, shell=True, check=True)

html_paths = glob("examples/*.html")
if len(html_paths) != len(notebooks):
raise ValueError(
f"expected {len(notebooks)} HTML files but found {len(html_paths)}"
)


for file_path in html_paths:
with open(file_path) as file:
html = file.read()

html = html.replace("<pre>", '<pre class="language-python">')
with open(file_path, "w") as file:
file.write(html)
28 changes: 13 additions & 15 deletions site/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,35 +12,33 @@
"build": "vite build",
"preview": "vite preview",
"serve": "vite build && vite preview",
"make-api-docs": "python ../assets/make_api_docs.py",
"make-html-examples": "jupyter nbconvert --to html ../examples/*.ipynb --no-prompt --template basic",
"changelog": "npx auto-changelog --package --output ../changelog.md --unreleased-only --hide-credit --commit-limit false"
},
"devDependencies": {
"@iconify/svelte": "^3.1.0",
"@sveltejs/adapter-static": "^2.0.1",
"@sveltejs/kit": "^1.12.0",
"@sveltejs/vite-plugin-svelte": "^2.0.3",
"@typescript-eslint/eslint-plugin": "^5.55.0",
"@typescript-eslint/parser": "^5.55.0",
"eslint": "^8.36.0",
"@iconify/svelte": "^3.1.1",
"@sveltejs/adapter-static": "^2.0.2",
"@sveltejs/kit": "^1.15.5",
"@sveltejs/vite-plugin-svelte": "^2.0.4",
"@typescript-eslint/eslint-plugin": "^5.58.0",
"@typescript-eslint/parser": "^5.58.0",
"eslint": "^8.38.0",
"eslint-plugin-svelte3": "^4.0.0",
"hastscript": "^7.2.0",
"highlight.js": "^11.7.0",
"mdsvex": "^0.10.6",
"prettier": "^2.8.5",
"prettier-plugin-svelte": "^2.9.0",
"prettier": "^2.8.7",
"prettier-plugin-svelte": "^2.10.0",
"rehype-autolink-headings": "^6.1.1",
"rehype-slug": "^5.1.0",
"svelte": "^3.57.0",
"svelte-check": "^3.1.4",
"svelte": "^3.58.0",
"svelte-check": "^3.2.0",
"svelte-multiselect": "^8.6.0",
"svelte-preprocess": "^5.0.3",
"svelte-toc": "^0.5.4",
"svelte-zoo": "^0.4.3",
"svelte2tsx": "^0.6.10",
"svelte2tsx": "^0.6.11",
"tslib": "^2.5.0",
"typescript": "^5.0.2",
"typescript": "^5.0.4",
"vite": "^4.2.1"
},
"prettier": {
Expand Down
Loading