Use js to show status of gh issues and PR #1896

Carreau · 2024-06-20T13:30:48Z

See #1895.

Not that I heve the right skills and am good at desing, just show what could be done.

Need to be pulled into a separate JS file and properely desinged.

Carreau · 2024-06-20T13:31:37Z

With my less than optimal design skills.

Carreau · 2024-08-15T15:15:59Z

Can we add @isabela-pf to the repo (even only with read access) so that we can assign her to review ?

choldgraf · 2024-08-15T15:26:44Z

I wonder if the tool that mystmd.org uses for GitHub hover cards could be repurposed here?

@agoose77 or @stevejpurves any thoughts on that?

Either way I think that updating the statuses is pretty nice 🙂

drammock · 2024-08-15T15:45:36Z

@Carreau there was a long-ish discussion before on whether this was a good idea, that ended in a stalemate: #1085

FWIW my views (one, two) on this haven't really changed since then. But there's enough new voices now that I could be outvoted!

EDIT: I realize now that the two proposals are different; here you just want to add the icons, not convert the link into the full PR title. I'm OK with adding/coloring the icons.

drammock · 2024-08-15T15:47:15Z

Can we add @isabela-pf to the repo (even only with read access) so that we can assign her to review ?

invitation sent!

isabela-pf

EDIT: I realize now that the two proposals are different; here you just want to add the icons, not convert the link into the full PR title. I'm OK with adding/coloring the icons.

I'm glad you called this out, because I was going to double check on the same after reading preceding issues. Thank you!

And many thanks to @Carreau for posting the screen shot of the result! That also makes it much easier for me to be sure what I'm looking at.

I'm going to write my comments as a numbered list for (hopefully) easier reference, but they are not reliant on one another.

The icon choice is good! I am glad to see them used in the same way as the GitHub reference discussed previously.
The addition of icons also makes sense considering GitHub as a reference. Do the icons get announced as a part of the link or in the tooltip, or are they visual only?
I think it was a good idea to map the status colors in the GitHub reference to the ones within the theme, and I think appropriate colors were chosen. However, in this situation, I do worry that they are close in value (light/darkness) and could be easily mixed up due to colorblindness, low or bright light situations, and any other situation where color is harder to discern. If the status is reiterated in the tooltip or in a text precursor to the #xxxx I think this is acceptable. If color is the only way to tell this status, I'd like to advise an additional way of communicating.

Please let me know if you have any questions for me! This is definitely on a good track, self-appointed "less than optimal design skills" or not.

Carreau · 2024-08-22T09:21:14Z

Thanks for the links to #1085, I missed it. I think this is indeed much narrower in scope.

2. The addition of icons also makes sense considering GitHub as a reference. Do the icons get announced as a part of the link or in the tooltip, or are they visual only?

Currently those are just visual, we can change if we want.

3. I think it was a good idea to map the status colors in the GitHub reference to the ones within the theme, and I think appropriate colors were chosen. However, in this situation, I do worry that they are close in value (light/darkness) and could be easily mixed up due to colorblindness, low or bright light situations, and any other situation where color is harder to discern. If the status is reiterated in the tooltip or in a text precursor to the #xxxx I think this is acceptable. If color is the only way to tell this status, I'd like to advise an additional way of communicating.

I think that's my main question, I'm really not good ad design/color. If you think there are changes we need to do and you can come up with colors that work with PST that would help me. I've mostly use red/green/purple because I know that's what GitHub is doing.

I don't want to bias the design process, but should the link be colors the same way as the icon, and should for example closed issues be strikethrough. I'm tempted to think no for strikethrough as most issue reference in documentation will be to merged PR and closed issues.

Carreau · 2024-08-29T15:13:00Z

I likely need to use font-awesome 6 instead of 5.

drammock · 2024-08-29T16:54:01Z

I likely need to use font-awesome 6 instead of 5.

or even octicons? I think a complete set for us would be:

PR open
PR closed (unmerged)
PR merged
issue open
issue closed (unsolved/solved is gray vs purple)

font awesome has code-merge and code-pull-request and circle-check but its circle-dot doesn't really resemble the octicon equivalent.

Carreau · 2024-08-30T07:29:25Z

I'm happy to use octicon, I just wanted to avoid an extra dependnecy by default.
I'klk see if I can make it work

isabela-pf

I'm weighing in one more time with more explicit approval on the design front in hopes that clarifies any lingering questions. In terms of what's been done so far, I find it matches GitHub's patterns of status icons and coloring, matches pydata-sphinx-theme's design system (uses color variables and relevant icons), and is mindful of dependencies that may mess with either of these patterns from a user experience/user interface perspective. That's all good to me!

I do think this is not a change that is needed to, for example, fix a bug or anything in the pydata-sphinx-theme, so if there is a choice to not move forward with this I also think that preserves a perfectly fine experience. But if it is wanted, this proof of concept seems like the right way to go about it from the design perspective.

trallard · 2024-09-06T13:56:41Z

We should be using FA 6 (this is the one we are vendoring with the theme).

drammock · 2024-09-06T18:04:20Z

We should be using FA 6 (this is the one we are vendoring with the theme).

Also despite my earlier comment about octicons, I won't object to using FA6 equivalents --- we can always switch to octicons later if necessary.

trallard · 2024-09-09T12:43:39Z

Sorry this was meant more at @Carreau since he is currently using FA 5

drammock · 2024-09-19T18:39:36Z

here's a screenshot of how this will look:

IMO we're not there yet:

open and merged PRs have same color
underline on the icon looks odd
I think I prefer the issue icon to be the "bullseye" (like github uses) rather than the "i in a circle", even though the FontAwesome bullseye doesn't perfectly match the Octicon one
not sure the "how to update kitchen sink" page is the right place in the docs to demo this. Maybe this section? https://pydata-sphinx-theme--1896.org.readthedocs.build/en/1896/user_guide/theme-elements.html#link-shortening-for-git-repository-services
viewing the link-shortening section in the prior bullet shows that the new JS is not applying correctly site-wide (possibly related to issues/ vs pull/ in the URL?)

Carreau · 2024-09-20T08:13:04Z

open and merged PRs have same color

Nah, that is because the PR I linked to has been merged since then...

underline on the icon looks odd

I did not figured out how to not underline it

I'll have a look at the rest.

github-actions · 2024-09-30T13:16:55Z

Coverage report

This PR does not seem to contain any modification to coverable code.

gabalafou · 2024-10-04T17:43:18Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+  <script type="module">
+      import { Octokit, App } from "https://esm.sh/octokit";
+      const octokit = new Octokit();
+      window.octokit = octokit;


Is there a good reason to make the octokit instance global?

Suggested change

window.octokit = octokit;

gabalafou

Reviewing this PR has given me some ideas for how to roll it out. I am inspired by the approach that you have taken with some of your other work (for example, with same-name-different-URL links).

I think it would be good to start with just our own website first, the PST docs. To do this, I believe you need to move the JavaScript and CSS into external files and then add them to the Sphinx config:

html_css_files = ["custom.css", ("github-matches.css", {"rel": "preload"})]
html_js_files = ["pydata-icon.js", "custom-icon.js", ("github-matches.js", {"type": "module"})]

Note: using rel=preload and type=module should ensure that both files are loaded asynchronously. I believe this will cause a layout shift since you apply a CSS class that adds content (via a :before pseudo-element) after the page is rendered, but I think this shouldn't be too disruptive, since it's just an icon... but I'm not sure, which is another reason why it would be prudent to release this first only on the PST docs.

Another idea I had while reviewing this PR is that maybe this is one of those things that's better to put in the docs as a recipe rather than including it by default in the code. A recipe gives theme adopters something to follow if they wish to add this behavior to their own website, but frees us from the urgency of having to fix the code if something breaks. A recipe is also frees us from needing to get the implementation right for every site that uses PST, because a recipe can be adapted by implementers for the specific needs of each site individually.

What do you think?

gabalafou · 2024-10-04T17:47:25Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

-  </noscript>
+      // Regular expression to match the desired GitHub issue URL pattern
+      // the s in pulls/issues is technically wrong but we find it sometimes.
+      const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(pull|issue)s?\/(\d+)$/;


optional trailing slash?

Suggested change

const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(pull|issue)s?\/(\d+)$/;

const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(pull|issue)s?\/(\d+)\/?$/;

untested regexes make me nervous...

gabalafou · 2024-10-04T17:51:00Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+      const githubIssueLinks = Array.prototype.filter.call(anchorTags, function(element) {
+          return regex.test(element.href);
+      });


The way you've written it is not wrong, but here is a bit more modern way to write the same thing:

Suggested change

const githubIssueLinks = Array.prototype.filter.call(anchorTags, function(element) {

return regex.test(element.href);

});

const githubIssueLinks = Array.prototype.filter.call(anchorTags, ({ href }) => regex.test(href));

gabalafou · 2024-10-04T17:52:50Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+      // we can sometime be throttled, or just refused connection,
+      // just do one request on root, and if not 200, just do nothing.
+      const root_res = await octokit.request('GET /');
+      if (root_res.status == 200) {


how do you feel about turning this into an early return?

gabalafou · 2024-10-04T17:54:33Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+          githubIssueLinks.map(async (atag) =>  {
+            const match = atag.href.match(regex);
+            if (match) {
+                const [fullUrl, username, repo,pr, issueNumber] = match;


Suggested change

const [fullUrl, username, repo,pr, issueNumber] = match;

const [fullUrl, username, repo, pr, issueNumber] = match;

gabalafou · 2024-10-04T17:55:42Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

-  </noscript>
+      // Regular expression to match the desired GitHub issue URL pattern
+      // the s in pulls/issues is technically wrong but we find it sometimes.
+      const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(pull|issue)s?\/(\d+)$/;


non-capturing group?

Suggested change

const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(pull|issue)s?\/(\d+)$/;

const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(?:pull|issue)s?\/(\d+)$/;

gabalafou · 2024-10-05T01:02:45Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+                if (res.data.pull_request !== undefined){
+                      console.debug('[PST] DEBUG: 4')
+                      pull_issue = 'pull';
+                      state = res.data.pull_request.merged_at != null ? 'merged': res.data.state ; 


could you comment this line? why can't we just set the variable to res.data.state

gabalafou · 2024-10-05T01:10:58Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+                console.debug('[PST] DEBUG: 1')
+                let pull_issue = 'unset';
+                console.debug('[PST] DEBUG: 2')
+                let state = 'unset';
+                console.debug('[PST] DEBUG: 3')
+                if (res.data.pull_request !== undefined){
+                      console.debug('[PST] DEBUG: 4')
+                      pull_issue = 'pull';
+                      state = res.data.pull_request.merged_at != null ? 'merged': res.data.state ; 
+                      console.debug('[PST] DEBUG: 4b')
+                } else {
+                      console.debug('[PST] DEBUG: 5')
+                      pull_issue = 'issue';
+                      state = res.data.state;
+                      console.debug('[PST] DEBUG: 5b')
+                }
+                console.log('[PST] adding classes to', pull_issue, state);
+                atag.classList.add(`pst-gh-${pull_issue}`)
+                atag.classList.add(`pst-gh-${state}`)


I felt a bit misled by this code because of the initial value "unset," which made me think that these are the default values, but in fact these values get reset in the unconditional else-block to "issue" and res.data.state. So I would rewrite it as:

Suggested change

console.debug('[PST] DEBUG: 1')

let pull_issue = 'unset';

console.debug('[PST] DEBUG: 2')

let state = 'unset';

console.debug('[PST] DEBUG: 3')

if (res.data.pull_request !== undefined){

console.debug('[PST] DEBUG: 4')

pull_issue = 'pull';

state = res.data.pull_request.merged_at != null ? 'merged': res.data.state ;

console.debug('[PST] DEBUG: 4b')

} else {

console.debug('[PST] DEBUG: 5')

pull_issue = 'issue';

state = res.data.state;

console.debug('[PST] DEBUG: 5b')

}

console.log('[PST] adding classes to', pull_issue, state);

atag.classList.add(`pst-gh-${pull_issue}`)

atag.classList.add(`pst-gh-${state}`)

let issueType = 'issue';

let state = res.data.state;

if (res.data.pull_request) {

issueType = 'pull';

if (res.data.pull_request.merged_at) {

state = 'merged';

}

}

atag.classList.add(`pst-gh-${issueType}`)

atag.classList.add(`pst-gh-${state}`)

gabalafou · 2024-10-05T01:14:18Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+      // we can sometime be throttled, or just refused connection,
+      // just do one request on root, and if not 200, just do nothing.
+      const root_res = await octokit.request('GET /');
+      if (root_res.status == 200) {


Suggested change

// we can sometime be throttled, or just refused connection,

// just do one request on root, and if not 200, just do nothing.

const root_res = await octokit.request('GET /');

if (root_res.status == 200) {

// GitHub's API server may throttle us or refuse the connection,

// so make a request on root, and if not 200, just do nothing.

const rootResponse = await octokit.request('GET /');

if (rootResponse.status == 200)

gabalafou · 2024-10-06T20:14:26Z

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

+                      //repo: 'REPO',
+                      //issue_number: 'ISSUE_NUMBER',
+                      headers: {
+                        'X-GitHub-Api-Version': '2024-09-30'


This line results in a 400 on the Read the Docs preview build, for example, on preview -community/topics/attribution:

"The version you specified in the "X-GitHub-API-Version" request header, "2024-09-30", is not a supported version. The following versions are currently supported: "2022-11-28" (most recent)."

Carreau marked this pull request as draft June 20, 2024 13:31

Carreau mentioned this pull request Aug 1, 2024

Team sync - August 1, 2024 Quansight-Labs/czi-scientific-python-mgmt#110

Open

Carreau mentioned this pull request Aug 15, 2024

Team sync - August 15, 2024 Quansight-Labs/czi-scientific-python-mgmt#114

Open

isabela-pf reviewed Aug 16, 2024

View reviewed changes

isabela-pf mentioned this pull request Aug 22, 2024

Team sync - August 22nd, 2024 Quansight-Labs/czi-scientific-python-mgmt#117

Open

Carreau mentioned this pull request Aug 29, 2024

Team sync - August 29th, 2024 Quansight-Labs/czi-scientific-python-mgmt#118

Open

isabela-pf approved these changes Sep 5, 2024

View reviewed changes

Carreau force-pushed the ghjs branch from f34eb67 to 38653da Compare September 11, 2024 10:22

Carreau requested review from isabela-pf and gabalafou September 19, 2024 11:22

Carreau marked this pull request as ready for review September 19, 2024 14:52

Carreau mentioned this pull request Sep 19, 2024

Team sync - Sep 19th, 2024 Quansight-Labs/czi-scientific-python-mgmt#126

Open

Carreau changed the title ~~POC: use js to show status of gh issues and PR~~ Use js to show status of gh issues and PR Sep 19, 2024

isabela-pf approved these changes Sep 19, 2024

View reviewed changes

Carreau force-pushed the ghjs branch from 38653da to a5197e7 Compare September 30, 2024 13:07

Carreau marked this pull request as draft September 30, 2024 13:26

gabalafou reviewed Oct 4, 2024

View reviewed changes

gabalafou requested changes Oct 6, 2024

View reviewed changes

trallard added this to the 0.16.1 milestone Oct 15, 2024

stuff

0299864

Carreau force-pushed the ghjs branch from a5197e7 to 0299864 Compare November 4, 2024 17:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use js to show status of gh issues and PR #1896

Use js to show status of gh issues and PR #1896

Carreau commented Jun 20, 2024

Carreau commented Jun 20, 2024

Carreau commented Aug 15, 2024

choldgraf commented Aug 15, 2024 •

edited

Loading

drammock commented Aug 15, 2024 •

edited

Loading

drammock commented Aug 15, 2024

isabela-pf left a comment

Carreau commented Aug 22, 2024

Carreau commented Aug 29, 2024

drammock commented Aug 29, 2024 •

edited

Loading

Carreau commented Aug 30, 2024

isabela-pf left a comment

trallard commented Sep 6, 2024

drammock commented Sep 6, 2024

trallard commented Sep 9, 2024

drammock commented Sep 19, 2024

Carreau commented Sep 20, 2024

github-actions bot commented Sep 30, 2024 •

edited

Loading

gabalafou Oct 4, 2024

gabalafou left a comment

gabalafou Oct 4, 2024

gabalafou Oct 4, 2024

gabalafou Oct 4, 2024

gabalafou Oct 4, 2024

gabalafou Oct 4, 2024

gabalafou Oct 5, 2024

gabalafou Oct 5, 2024

gabalafou Oct 5, 2024

gabalafou Oct 6, 2024

	const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(pull\|issue)s?\/(\d+)$/;
	const regex = /^https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/(pull\|issue)s?\/(\d+)\/?$/;

	const [fullUrl, username, repo,pr, issueNumber] = match;
	const [fullUrl, username, repo, pr, issueNumber] = match;

Use js to show status of gh issues and PR #1896

Are you sure you want to change the base?

Use js to show status of gh issues and PR #1896

Conversation

Carreau commented Jun 20, 2024

Carreau commented Jun 20, 2024

Carreau commented Aug 15, 2024

choldgraf commented Aug 15, 2024 • edited Loading

drammock commented Aug 15, 2024 • edited Loading

drammock commented Aug 15, 2024

isabela-pf left a comment

Choose a reason for hiding this comment

Carreau commented Aug 22, 2024

Carreau commented Aug 29, 2024

drammock commented Aug 29, 2024 • edited Loading

Carreau commented Aug 30, 2024

isabela-pf left a comment

Choose a reason for hiding this comment

trallard commented Sep 6, 2024

drammock commented Sep 6, 2024

trallard commented Sep 9, 2024

drammock commented Sep 19, 2024

Carreau commented Sep 20, 2024

github-actions bot commented Sep 30, 2024 • edited Loading

Coverage report

Choose a reason for hiding this comment

gabalafou left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

choldgraf commented Aug 15, 2024 •

edited

Loading

drammock commented Aug 15, 2024 •

edited

Loading

drammock commented Aug 29, 2024 •

edited

Loading

github-actions bot commented Sep 30, 2024 •

edited

Loading