scnc
/
qiskit-documentation
mirror of https://github.com/Qiskit/documentation.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add .gitattributes and guide for diffing objects.inv (#962) 

This PR adds instructions on setting up Git to use
[`sphobjinv`](https://github.com/bskinn/sphobjinv) to display diffs for
`objects.inv`.

Since `objects.inv` is compressed, we can't review changes through `git
diff`. Git _does_ tell you if the file has changed, but this isn't that
helpful as the compressed file can be different even if the uncompressed
contents are the same.

Git will default back to binary diff if it doesn't find a rule in
`.gitconfig` so adding `.gitattributes` shouldn't disrupt contributors
that don't follow the guide.

Hopefully this information will help keep more eyes on the file and spot
any unintended changes.

Here's an example of it in action (downgrading qiskit to 0.46):
<img width="950" alt="Screenshot 2024-03-05 at 14 20 04"
src="https://github.com/Qiskit/documentation/assets/36071638/5aabaca4-d175-4871-84c5-e583069e0c1a">
This commit is contained in:
Frank Harkins 2024-03-05 14:58:23 +00:00 committed by GitHub
parent be142f5c0e
commit 8492292da5
2 changed files with 17 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitattributes vendored Normal file
View File

@ -0,0 +1 @@
objects.inv diff=objects_inv

16
README.md
View File

@ -347,6 +347,22 @@ Follow the same process above for new API docs, other than:
If the version is not for the latest stable minor release series, then add `--historical` to the arguments. For example, use `--historical` if the latest stable release is 0.45.\* but you're generating docs for the patch release 0.44.3.
### View diff for `objects.inv`
Since `objects.inv` is compressed, we can't review changes through `git diff`. Git _does_ tell you if the file has changed, but this isn't that helpful as the compressed file can be different even if the uncompressed contents are the same.
If you want to see the diff for the uncompressed contents, first install [`sphobjinv`](https://github.com/bskinn/sphobjinv).
```sh
pipx install sphobjinv
```
The add the following to your `.gitconfig` (usually found at `~/.gitconfig`).
```
[diff "objects_inv"]
textconv = sh -c 'sphobjinv convert plain "$0" -'
```
# How to write the documentation
We use [MDX](https://mdxjs.com), which is like normal markdown but adds extensions for custom components we have.