-
Notifications
You must be signed in to change notification settings - Fork 56
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1299 from nexusformat/1254-add-list-of-contributo…
…rs-to-appdef add ability to add contributor information to html pages (#1254)
- Loading branch information
Showing
8 changed files
with
206 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,30 @@ | ||
import re | ||
|
||
# a custom sphinx extension that is connected to the source-read hook for rst files, | ||
# the purpose is to read all of the contributor information from the rst file and | ||
# place it in a string variable that will be used in the sourcelink.html jinja template | ||
# that has been over ridden and sits in the _templates directory to produce the | ||
# contributor information on the for right sidebar of the html pages | ||
|
||
variables_re = re.compile(r"\|(\w+)\| replace::\s(.+)") | ||
|
||
|
||
def extract_contributor_vars(app, docname, source): | ||
# Read the RST file content | ||
content = source[0] | ||
|
||
# Extract variables using regular expressions | ||
variables = variables_re.findall(content) | ||
|
||
# Create a dictionary to store the extracted variables | ||
# this will create a list of single strings each of which contain the info about the contributor | ||
extracted_variables = [var[1] for var in variables] | ||
if "variables" not in app.config.html_context.keys(): | ||
app.config.html_context["variables"] = {} | ||
|
||
# Add the extracted variables to the Jinja environment | ||
app.config.html_context["variables"][docname] = extracted_variables | ||
|
||
|
||
def setup(app): | ||
app.connect("source-read", extract_contributor_vars) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
import os | ||
|
||
import requests | ||
|
||
|
||
def format_author_name(nm): | ||
""" | ||
make sure all words in name start with a capital | ||
""" | ||
nms = nm.split(" ") | ||
auth_nm = " ".join([n.capitalize() for n in nms]) | ||
return auth_nm | ||
|
||
|
||
def get_github_profile_name(email): | ||
""" | ||
given an email addr return the github login name | ||
""" | ||
email = email.replace(" ", "") | ||
nm = email.split("@")[0] | ||
return nm | ||
|
||
|
||
def get_file_contributors_via_api(repo_name, file_path): | ||
""" | ||
This function takes the repo name (ex:"definitions") and relative path to the nxdl | ||
file (ex: "applications/NXmx.nxdl.xml") and using the github api it retrieves a dictionary | ||
of committers for that file in descending date order. | ||
In order to increase the capacity (rate) of use of the github API an access token is used if it exists | ||
as an environment variable called GH_TOKEN, in the ci yaml file this is expected to be assigned from the secret | ||
object like this | ||
env: | ||
GH_TOKEN: ${{ secrets.GH_TOKEN }} | ||
With the access token the rate is 5000 times per hour and without it is 60 | ||
returns a sorted dict of unique contributors to a file, or None if no GH_TOKEN has been defined in os.environ | ||
""" | ||
have_token = False | ||
if "GH_TOKEN" in os.environ.keys(): | ||
access_token = os.environ["GH_TOKEN"] | ||
if len(access_token) > 0: | ||
have_token = True | ||
else: | ||
# because the environment does not contain GH_TOKEN, assume the user wants to build the | ||
# docs without contributor info | ||
return None | ||
|
||
contrib_skip_list = ["GitHub"] | ||
url = f"https://api.github.com/repos/nexusformat/{repo_name}/commits" | ||
params = {"path": file_path} | ||
headers = {} | ||
if have_token: | ||
# Set the headers with the access token | ||
headers = { | ||
"Authorization": f"token {access_token}", | ||
"Accept": "application/vnd.github.v3+json", | ||
} | ||
|
||
response = requests.get(url, params=params, headers=headers) | ||
commits = response.json() | ||
if response.status_code != 200: | ||
# if its 403: the max rate per hour has been reached | ||
raise Exception( | ||
f"access_token={access_token}, {commits['message']},{commits['documentation_url']}" | ||
) | ||
|
||
contributor_names = set() | ||
contribs_dct = {} | ||
_email_lst = [] | ||
for commit_dct in commits: | ||
if commit_dct["committer"] is not None: | ||
contributor = commit_dct["commit"]["committer"]["name"] | ||
if contributor in contrib_skip_list: | ||
continue | ||
contributor_names.add(contributor) | ||
if commit_dct["commit"]["committer"]["email"] not in _email_lst: | ||
_email = commit_dct["commit"]["committer"]["email"] | ||
_email_lst.append(_email) | ||
contribs_dct[commit_dct["commit"]["committer"]["date"]] = { | ||
"name": format_author_name( | ||
commit_dct["commit"]["committer"]["name"] | ||
), | ||
"commit_dct": commit_dct, | ||
} | ||
|
||
# sort them so they are in descending order from newest to oldest | ||
sorted_keys = sorted(contribs_dct.keys(), reverse=True) | ||
sorted_dict = {key: contribs_dct[key] for key in sorted_keys} | ||
|
||
return sorted_dict |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
{# | ||
basic/sourcelink.html | ||
~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Sphinx sidebar template: "show source" link. | ||
|
||
:copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS. | ||
:license: BSD, see LICENSE for details. | ||
#} | ||
{%- if show_source and has_source and sourcename %} | ||
<div role="note" aria-label="source link"> | ||
<h3>{{ _('This Page') }}</h3> | ||
<p>Have a Question? <a href="https://github.com/nexusformat/definitions/issues/new">Get help</a></p> | ||
<ul class="this-page-menu"> | ||
<style> | ||
.avatar-container { | ||
display: flex; | ||
align-items: center; | ||
} | ||
|
||
.avatar { | ||
width: 32px; | ||
height: 32px; | ||
border-radius: 50%; | ||
margin-right: 5px; | ||
} | ||
</style> | ||
{% set nx_class_nm = sourcename|replace(".rst.txt","") %} | ||
{% if variables[nx_class_nm]|length > 0 %} | ||
<p> Contributors </p> | ||
{% else %} | ||
{% endif %} | ||
<div class="avatar-container"> | ||
{% for vars_string in variables[nx_class_nm] %} | ||
{% set var_list = vars_string.split('|') %} | ||
{% set tooltip_string = var_list[0] ~ " " ~ var_list[3] %} | ||
<a href="https://github.com/{{ var_list[1] }}" | ||
class="" | ||
title="{{ tooltip_string }}" | ||
data-hovercard-type="user" data-hovercard-url="/users/{{ var_list[1] }}/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self"> | ||
<img class="avatar circle" src="{{ var_list[2] }}" data-view-component="true" alt="GitHub Avatar"> | ||
{% endfor %} | ||
</ul> | ||
</div> | ||
{%- endif %} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters