search

jbms / sphinx-immaterial

Adaptation of the popular mkdocs-material material design theme to the sphinx documentation system
https://jbms.github.io/sphinx-immaterial/
Other
177 stars 28 forks source link

use libgit2 directly in merge script #309

Closed 2bndy5 closed 5 months ago

2bndy5 commented 5 months ago

We're way behind upstream and I ran the merge script to see what an update would look like. Unfortunately, it is failing. Whenever git apply --3way returns a non-zero exit code, we have to manually go and hand-prepare certain files that can't be patched cleanly (for various reasons).

I recently discovered the awesomeness of pygit2 (a libgit2 binding for python). I think the merge script could be rewritten in a platform agnostic way (currently relies on Linux) using pygit2 because all of git CLI uses libgit2 under the hood. It would also allow for better handling of certain files programmatically (eg newly created files from upstream).

PS - Using WSL to run the merge script now causes a lot of errors in file attributes with errors like:

expected 100755; got 100644

I had to dual boot into my Kubuntu install just to run the merge script. Using pygit2 might also relieve these errors.

Just for reference/refresher on why the merge script only works on Linux: https://github.com/jbms/sphinx-immaterial/blob/c9d7b87638ac7df100f816ed99aa86a76377d4bc/merge_from_mkdocs_material.py#L14-L22

jbms commented 5 months ago

The issue was due to the rename from src/assets -> src/templates/assets.

I modified the merge script to use git-rebase, which handles renames properly.

https://github.com/jbms/sphinx-immaterial/pull/310

The exclusions might need further fixes.

As far as converting it to use pygit2, in principle that could make sense but I'm not sure it is worth the trouble.

Note that libgit2 seems to be used by various tools, including github, but is a separate implementation from what underlies the official git command-line tools.

2bndy5 commented 5 months ago

I'll count git-rebase as the acceptable solution for this. If it works then it works. No need to re-implement what the git CLI does through libgit2 API if it isn't broken.