Add preparation step for Jekyll deployment and include static files by cogsworth37 · Pull Request #4631 · materialsproject/pymatgen

cogsworth37 · 2026-04-10T16:59:33Z

Summary

Major changes:

Fixes broken styles/JS introduced by #4626 — the CI migration didn't account for Sphinx asset handling.

Checklist

Google format doc strings added. Check with ruff.
Type annotations included. Check with mypy.
Tests added for new features/fixes.
If applicable, new classes/functions/modules have duecredit @due.dcite decorators to reference relevant papers by DOI (example)

Tip: Install pre-commit hooks to auto-check types and linting before every commit:

pip install -U pre-commit
pre-commit install

DanielYang59 · 2026-04-10T17:27:49Z

.github/workflows/jekyll-gh-pages.yml

          rm -rf .apidoc_merge
          rm apidoc/*.rst
          mv html/pymatgen*.html .
          mv html/modules.html .


Great! thanks for fixing this. I have no experience with sphinx/jekyll, but I think the copy step could just go here for simplicity?

I did it this way to create a clear boundary. the cp -r command must be run after the sphinx-build command. while I could put it at the end of the block, I wanted to create no confusion if the order gets messed up.

I think both HTML and static are built by sphinx, looks quite confusing to me to copy HTML first and then in another step copy static?

That is a fair point. would you prefer a collapse into that block or all rm/mv/cp commands be moved to a more operational block?

maybe let's combine them? making this workflow shorter would make later reading/debug a bit easier (personally)...

DanielYang59 · 2026-04-10T17:32:59Z

.github/workflows/jekyll-gh-pages.yml

pymatgen doesn't have docs optional dependency

WARNING: pymatgen 2026.3.23 does not provide the extra 'docs'

it's currently declared via uv dependency group docs

https://github.com/materialsproject/pymatgen/blob/master/pyproject.toml#L287

these two steps (pip install pymatgen and then sphinx) could just be uv sync --group docs

can you also help me remove docs from default dependency group (and that TODO)? I believe it's not needed anymore

pymatgen/pyproject.toml

Lines 283 to 285 in f475a89

[tool.uv]

# TODO: remove `docs` once doc generation is automated

default-groups = ["dev", "test", "lint", "docs"]

Updated to use uv sync --group docs and removed docs from the default groups

great thanks

DanielYang59 · 2026-04-10T17:35:40Z

.github/workflows/jekyll-gh-pages.yml

these two sphinx commands should be called via uv instead, i.e. uv run sphinx-xxx ...

Updated to use uv commands here

DanielYang59 · 2026-04-10T18:02:12Z

.github/workflows/jekyll-gh-pages.yml

+        working-directory: docs
+        run: |
+          cp -r html/_static _static
+          touch .nojekyll


Curious what does .nojekyll do (as i don't have experience with jekyll at all)? I see here:

It is now possible to completely bypass Jekyll processing on GitHub Pages by creating a file named .nojekyll in the root of your pages repo and pushing it to GitHub.

But I think in the _config.yml there is already an explicit include: _static tag? does these two serve different purposes?

This should only be necessary if your site uses files or directories that start with underscores since Jekyll considers these to be special resources and does not copy them to the final site.

It does not. it's an extra extra guard. I usually like to add protections in multiple places as long as it's functionally consistent. just a quirk of mine, happy to remove if you don't feel it's necessary.

I guess we're not talking about security where we need layers of defense here... personally I think if one config gets the job done then we might not need to duplicate here (less confusion for later readers... people like me would think they're serving different purposes)

…ion and remove docs from default groups in pyproject.toml

…sistency

DanielYang59 · 2026-04-11T08:40:21Z

Great style seems to be working now!

DanielYang59 · 2026-04-11T09:12:41Z

I noticed the links to sources are not working (for both core and non-core modules), not sure if you would have time for a look? @cogsworth37

For example for non-core ext:

# Current URL generated in docs
- https://github.com/materialsproject/src/pymatgen/ext/optimade.py

# Correct URL
+ https://github.com/materialsproject/pymatgen/blob/master/src/pymatgen/ext/optimade.py

For core Ion it points to the wrong repo:

# Current URL generated in docs
- https://github.com/materialsproject/pymatgen/blob/v2026.4.7/src/pymatgen/core/ion.py

# Correct URL
+ https://github.com/materialsproject/pymatgen-core/blob/main/src/pymatgen/core/ion.py

shyuep · 2026-04-11T09:35:59Z

The sources are in different locations. The core classes are in the pymatgen-core repo. Actually, we can also just use the submodule since it is already linked.

Add preparation step for Jekyll deployment and include static files

b03dfe8

cogsworth37 requested review from mkhorton and shyuep as code owners April 10, 2026 16:59

DanielYang59 reviewed Apr 10, 2026

View reviewed changes

cogsworth37 added 2 commits April 10, 2026 14:27

Update Jekyll deployment workflow to use UV for documentation generat…

b767d91

…ion and remove docs from default groups in pyproject.toml

Moved the prepare step into the Generate Sphinx API docs step for con…

3750f4a

…sistency

shyuep merged commit ccc16d2 into materialsproject:master Apr 11, 2026
6 checks passed

	[tool.uv]
	# TODO: remove `docs` once doc generation is automated
	default-groups = ["dev", "test", "lint", "docs"]

Conversation

cogsworth37 commented Apr 10, 2026

Summary

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielYang59 Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielYang59 Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielYang59 Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

DanielYang59 commented Apr 11, 2026

Uh oh!

DanielYang59 commented Apr 11, 2026

Uh oh!

shyuep commented Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DanielYang59 Apr 10, 2026 •

edited

Loading

DanielYang59 Apr 10, 2026 •

edited

Loading

DanielYang59 Apr 10, 2026 •

edited

Loading