New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reworked team page look and building process #2855
Reworked team page look and building process #2855
Conversation
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? |
Good point, I think it might be nothing that prevents us from using Jinja itself. That said, I'm not 100% sure. 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 |
Nice work! Very flexible, and hopefully easy to maintain. |
👍 |
I've started using Jinja2 instead of Mustache for this. I'll update my main post accordingly. |
looks awesome! 🔥 |
I know it's not ready for merging yet, but just approving since it looks great! In response to a few of your questions:
|
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. And for 2: I'm not sure how to make this clear. Luckily, this I (again) updated the main message according to the last changes with photos. |
Hello!
Pull request overview
web/_templates/team.html
: A HTML format which is filled with data from a new file calledweb/team/team.json
.web/conf.py
to automatically generate the Team page upon Sphinx build.web/images
folder toweb/_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:
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 usingteam.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 withsphinx -E ./web ./build
like always. Easy.The
team.json
formatThe sample
team.json
that I've uploaded with this PR looks very similar to this:The top-most two keys are
current
andformer
, and each of these become a separate file:current_team.html
andformer_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.Edit: Thisphoto_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.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
and2020-
.Each of the optional keys can just be left out (e.g.
photo_path
for the bottom 2, andpersonal_website_url
oractive_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 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
._static/img
, perhaps use that one, instead fo_static/image
.