Reworked team page look and building process

[tomaarsen]

Hello!

Pull request overview

• Create web/_templates/team.html: A HTML format which is filled with data from a new file called web/team/team.json.
• Created some css to go along with this new team page.
• Updated web/conf.py to automatically generate the Team page upon Sphinx build.
• Moved web/images folder to web/_static/images.

Note:

This PR is not ready for merging. It's a draft that requires work. Currently, it's filled with a bogus team which needs to be filled out.

Sample screenshot

Note that the data for this team is bogus, and that I zoomed the page out further than normal for a larger screenshot. I've provided this screenshot to give an overview of the page as it stands after building while checked out at this PR.

My name in the top left links to a personal website, while clicking on my photo or on my github username links you to my GitHub page. The same goes for all member cards.

Details

Our documentation/website builder Sphinx works with .rst files. However, such files do not provide the freedom which I'd like to have with the team page. My goal was simple: make the process of adding or updating the list of team members as simple as possible, while making the team page visually fit with the rest of the documentation. Another goal was to provide options for team members to show whatever information they want.
This required html files, which can be imported in ReST like:

.. raw:: html
   :file: team/current_team.html

I used this to embed HTML files within the website on the Team page. This looks very natural to the end user, as you can see in the screenshot.

That all said, it's crucial that updating the team page is not a pain.
That's why I've opted for a Mustache file. Such a file is an HTML template, that uses "tags" similarly to Jinja (if you're familiar with that) to generate full-blown HTML pages.
It allowed me to easily create a format file (team.mustache) which is filled with some data (team.json) to generate HTML pages which are used by Sphinx.
Edited:
I've now opted for Jinja2 instead, as I used that for creating the HOWTO pages as well. The new web/_templates/team.html is a HTML file with Jinja2 tags to generate HTML pages using team.json data.

Now, to further aid the process of automating the website build process, I've created a function in web/conf.py which generates these files before Sphinx places them in the final website.

In short, all we need to do is fill out team.json, and then re-generate the website with sphinx -E ./web ./build like always. Easy.

The team.json format

The sample team.json that I've uploaded with this PR looks very similar to this:

{
    "current": [
        {
            "full_name": "Tom Aarsen",
            "github_username": "tomaarsen",
            "personal_website_url": "https://www.tomaarsen.com",
            "location": "Nijmegen, Netherlands",
            "role": "Core Maintainer. Issue triaging, bug fixing, documentation, website.",
            "active_range": "Since 2020"
        },
        {
            "full_name": "Arbitrary Human",
            "github_username": "this-user-hopefully-does-not-exist",
            "personal_website_url": "https://www.google.com",
            "location": "Within the Milky Way, hypothetically",
            "role": "Introducing bugs",
            "active_range": "For far too long"
        }
    ],
    "former": [
        {
            "full_name": "Someone else",
            "github_username": "presumably-this-user-doesnt-exist-either",
            "location": "Earth",
            "role": "Absolutely nothing",
            "active_range": "Who knows?"
        }
    ]
}

The top-most two keys are current and former, and each of these become a separate file: current_team.html and former_team.html. Both of these files are included in the team page on the website, under their own section. Each of these keys contains lists of members. Each member in these lists can have the following options:

• full_name - mandatory. Speaks for itself.
• github_username - mandatory. Also used for creating a link to the github page.
• personal_website_url - optional. If set, then the team member's name becomes a link to this page.
• photo_path - optional. Final path to a square image rendered beside the team member. If set, then the photo can also be clicked for a link to the team member's GitHub page. Edit: This photo_path parameter is no longer required, as we now automatically use the profile picture on GitHub as the user's picture.
• location - optional. Speaks for itself.
• role - optional. Speaks for itself.
• active_range - optional. Speaks for itself. Later on we can discuss a format for these ranges, e.g. 2014-2018 and 2020-.

Each of the optional keys can just be left out (e.g. photo_path for the bottom 2, and personal_website_url or active_range for the bottom one), and the template will react accordingly.

Potential for changes

I want to make something clear - everything you see here can be easily modified. If you don't really like some of the wording, or the design, then feel free to let me know. I'd love for this to become a page that team members are proud to refer to. It's very easy to add an optional extra header for a team member too, for those who are interested. E.g. "Research interest" or something. Anything goes.

Some ideas

• ~~The photo can also link to the team member's personal website, if they supply one, rather then their GitHub page. ~~
• The photo can perhaps also be taken directly from the team member's GitHub page. That way, everyone might have a picture without having to go through the hastle of uploading one. That said, it removes some freedom and choice.
  The photo is now taken from the GitHub page, like described here. See the comments below for more information.

What now?

I'm looking for feedback on the look of everything, and would like to extend the team.json file with information of other team members. I will need help with this.

To do:

(This is mostly for me to keep track of things)

• tree.gif is packaged twice, once under _images and once under _static/images.
• There's also a _static/img, perhaps use that one, instead fo _static/image.

---

• Tom Aarsen

[iliakur]

Very quick question, sadly no time to review this deeply. afaict, sphinx comes with jinja by default. What prevents us from using that and opting for mustache?

[tomaarsen]

Good point, I think it might be nothing that prevents us from using Jinja itself. That said, I'm not 100% sure.
We would need to use html_additional_pages to provide a template, just like I've done in e.g. https://github.com/tomaarsen/nltk_theme/blob/master/nltk_theme/layout.html. That said, I'm not sure how to supply additional data to this template.

I'll try to have a look at it. If it turns out to be just as easy as ths current solution, then perhaps it could be an example of how to update the Example Usage page too. (i.e. https://www.nltk.org/howto/)

[stevenbird]

Nice work! Very flexible, and hopefully easy to maintain.

[purificant]

👍

[tomaarsen]

I've started using Jinja2 instead of Mustache for this. I'll update my main post accordingly.

[dannysepler]

looks awesome! 🔥

[dannysepler]

I know it's not ready for merging yet, but just approving since it looks great! In response to a few of your questions:

1. photo_path pointing a user's repo does feel nice and easy! even at the loss of a bit of freedom.
   • i wonder how hard this will be, i think if you had some way to get a user's ID from their username, you could point to this link https://avatars.githubusercontent.com/u/3710083 (swapping out the ID number at the end)
2. Regarding the optional vs required fields, how will users know which is required?
   • i actually don't know what to do here, potentially nesting a required list and an optional list. but that feels verbose

[tomaarsen]

@dannysepler

Regarding 1: I did some more research into the matter, and it turns out that it's truly as simple as going to https://www.github.com/dannysepler.png! GitHub redirects it for you.
So, I'm using that now! All it took was 3 lines of changes in web/_templates/team.html.

And for 2: I'm not sure how to make this clear. Luckily, this team.json file will only need to be modified by team members, who will hopefully be able to find the documentation of this PR. Perhaps some of the explanation can be pasted into conf.py too (i.e. the file that is ran to actually generate the files)

I (again) updated the main message according to the last changes with photos.