Skip to content

Commit ba3af47

Browse files
RSTZZZRSTZZZ
committed
Add documentation
1 parent 2d90f3c commit ba3af47

9 files changed

+478
-469
lines changed

‎README.md

+7-403
Large diffs are not rendered by default.

‎documentation/advanced_mode.md

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Advanced Information
2+
3+
We are using minimal-mistakes & Jekyll.
4+
5+
For any type of page or post (publication, blog post, course description), we use something called ["Front Matters"](https://jekyllrb.com/docs/front-matter/) to tell Jekyll about the purpose of the file. This is a block of YAML text at the beginning of the file. The rest of the file is regular [markdown](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
6+
7+
Guide: https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/
8+
Layout / YAML Front-matter: https://mmistakes.github.io/minimal-mistakes/docs/layouts/
9+
10+
## Creating Modules
11+
12+
For our custom Front Matter / modules, you can find the **html** page under `_includes`.
13+
14+
For the CSS, we write it in **SASS**, and put it under `_sass/custom`. We then add a `@include custom/{module-name}.scss`.
15+
16+
We try not to have many custom **javascript**, but if there is, it is under `_includes/head/custom.html`
17+
18+
19+
## Important Dependecies
20+
21+
It is layed out such that we do not repeat yourself (DRY). Hence, we make use of the file layout & file name.
22+
23+
### Research Directions (on the Home Page)
24+
25+
On the home page (`_pages/home.md`), we have the following line:
26+
> {% include research-directions.html category="research-directions"%}
27+
28+
Here, it automatically collects any `.md` files under `_research_directions`. Please note, these files should follow a similar layout outlined [here](./research_direction_layout.md)
29+
30+
31+
### Topics (on the research direction page)
32+
33+
Within the research_direction, you may find the following:
34+
> {% include sub_research-directions.html category="temporal-graph-learning" %}
35+
36+
Here, it automatically finds any `.md` files under `_research_directions/{RESEARCH DIRECTION}`. Please note, these files should follow a similar layout outlined [here](./topic_layout.md)
37+
38+
E.g. If the `RESEARCH DIRECTION` is `temporal-graph-learning`, then you should make a directory under `_research_directions` called `temporal-graph-learning`. When using calling `sub_research-directions.html`, also pass in `temporal-graph-learning`.
39+
40+
### Selected Publications (on research direction / topic pages)
41+
42+
This is used within `RESEARCH DIRECTION` page or `TOPIC` page.
43+
44+
> {% include posts-highlighted-publications.html taxonomy="TGA" %}
45+
46+
Here, we automatically collect papers (md files under `_posts`). Within these md files, we search for those with categories that match the given taxonomy.
47+
48+
E.g. For the topic _Temporal Graph Applications_, we use the key `TGA`. Hence, we add `TGA` as one of the categories for a paper we want to shown on the _Temporal Graph Applications_ page.
49+
50+
51+
52+
53+
54+
55+
56+
## Modify pages
57+
58+
> [!WARNING]
59+
> *This section is for advanced users. You will likely not need it unless you are intend to maintain this website or fix specific issues with page rendering*
60+
61+
To modify a page, navigate to [_pages](_pages/) and update the desired file. If you add a new file, you will also need to edit the [_data/navigation.yml](_data/navigation.yml) file with the correct relative URL.
62+
63+
The following pages are mostly likely to be frequently updated:
64+
65+
* [home](_pages/home.md)
66+
* [contact](_pages/contact.md)
67+
68+
The following pages are not likely to be frequently updated:
69+
70+
* [people](_pages/people.md)
71+
* [publications](_pages/publications.md)
72+
* [blog](_pages/blog.md)
73+
* [teaching](_pages/teaching.md)
74+
75+
Note: If you want to add new content to one of the pages above, please refer to the section on [creating a post](#creating-a-post).
76+
77+
The following files are only meant to be modified by the site maintainer in rare cases:
78+
79+
* [404](_pages/404.md)
80+
* [category-archive](_pages/category-archive.md)
81+
* [tag-archive](_pages/tag-archive.md)
82+
* [year-archive](_pages/year-archive.md)
83+
84+
### Removing a page
85+
86+
To remove a page, delete the desired file in `_pages/` and delete the corresponding entry in [_data/navigation.yml](_data/navigation.yml).
87+
88+
89+
## Maintaining / Local Development
90+
91+
> [!WARNING]
92+
> *This section is meant for the maintainer(s) or developers of the site. Please consult the faculty members for more information on how to become a maintainer.*
93+
94+
### Setup
95+
96+
#### Codespace
97+
98+
Most of the dependencies (`jekyll`, `ruby`, `gem`, Python `requirements.txt`, etc.) are already installed thanks to automations in `.devcontainer/devcontainer.json`. You can simply open the repo in a codespace and start working.
99+
100+
#### Local
101+
102+
You will need to install the python dependencies by running (from inside project directory):
103+
104+
```
105+
pip3 install --user -r src/python/requirements.txt
106+
```
107+
108+
You will need to install ruby and gem to use `jekyll` locally. This is only if you want to compile and run this site locally. If you want to modify a markdown file or a yaml file, you don't need to do that; please refer to the sections above for instructions. For the instructions, see [Jekyll installation](https://jekyllrb.com/docs/installation/) (e.g. [on Ubuntu](https://jekyllrb.com/docs/installation/ubuntu/)).
109+
110+
### Running the site in development mode
111+
112+
To run the site locally (or remotely on Codespaces), use the last command in the quickstart:
113+
114+
```bash
115+
bundle exec jekyll serve
116+
```
117+
118+
We use the `minimal-mistakes` theme. Specifically, we use the `remote-theme` installation method, which is why the repo doesn't contain all of the html, css, and yaml files required for the theme. To learn more, read [this minimal-mistakes doc section](https://mmistakes.github.io/minimal-mistakes/docs/quick-start-guide/#remote-theme-method). Note we are using a specific version of the theme, which can be found on `_config.yml`.
119+
120+
### Editing SCSS
121+
122+
If you need to modify some CSS attributes directly, you need to use [sass](https://sass-lang.com/documentation/syntax), or directly write CSS (which is still valid). You can create a new file in [_sass/custom](_sass/custom) and import it inside [_sass/main.scss](_sass/main.scss). Note that all files in [_sass/custom](_sass/custom) were added by the maintainers of this repo, in addition to the original styling provided by minimal-mistakes.
123+
124+
Here's a brief description:
125+
126+
* [_sass/custom/display-publications.scss](_sass/custom/display-publications.scss): Some custom CSS for styling the publications on `/publications/`, which did not have the same format in the original minimal-mistakes theme.
127+
* [_sass/custom/no-sidebar.scss](_sass/custom/no-sidebar.scss): This adds an option to shift the page to the left side when there's no sidebar. Search for `no-sidebar` in [_config.yml](_config.yml) to see how to use it, or read [this post](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#layout-based-and-user-defined-classes).
128+
* [_sass/custom/people-card.scss](_sass/custom/people-card.scss): This is a custom CSS for styling the "cards" for each member in `/people/`.
129+
* [_sass/custom/skin.scss](_sass/custom/skin.scss): This is a custom CSS for styling the skin of the website.
130+
131+
### Custom `_includes/`
132+
133+
`_includes/` contains HTML and MD files that can be called from any page. It's something specific to Jekyll. To use it in your page, simply create an HTML file at `_includes/my-file.html` and add the following to the front matter of your page:
134+
135+
```
136+
{% include "my-file.html" %}
137+
```
138+
139+
We have 5 custom `include` HTML files for this website. You may take a look at their usage by searching `include <name>.html` across the codebase.
140+
141+
### Custom `_layouts/`
142+
143+
You can create custom html layouts in `_layouts/`. For example, you can create a file called `my-layout.html`. It should contain a front matter block, followed by the HTML content:
144+
145+
```html
146+
---
147+
layout: archive
148+
---
149+
150+
{{ content }}
151+
152+
<div>
153+
{% include ... %}
154+
</div>
155+
```
156+
157+
To use them, simply specify, in the front matters of a page in `_page/`:
158+
159+
```yaml
160+
---
161+
layout: publication
162+
---
163+
```
164+
165+
Example: In our case, we have a custom `publications.html` layout for the `/publications/` page.
166+
167+
### Github Actions
168+
169+
We use Github Actions to automate processes. You can find the files in [`.github/workflows/`](.github/workflows/), and see their status in the "Actions" tab. This requires you to use YAML.
170+
171+
### Python scripts
172+
173+
Some Python scripts are ran inside the actions. You can find them in [`src/python/`](src/python). If you want to run them locally, you can use the following command:
174+
175+
```bash
176+
pip install -r src/python/requirements.txt
177+
python src/python/<script>.py
178+
```
179+
180+
Replace `<script>` with the name of the script. If you want to add some library, you can add it to the requirements.txt file. Make sure to include the full version: `<library>==<version>`, or else it might break automation. For example, if you want to use the `requests` library, you can add it to the requirements.txt file as `requests==2.18.4`.
181+
182+
### Issue forms
183+
184+
To modify an issue form, simply edit the corresponding form in [`.github/ISSUE_TEMPLATE`](.github/ISSUE_TEMPLATE). Note that if you make some major change, you might need to modify the python scripts. Thus, it is recommended to test that on a fork in order to avoid breaking the automation on the main repo.
185+
186+
### Troubleshooting
187+
188+
If you have a question about using Jekyll, start a discussion on the [Jekyll Forum](https://talk.jekyllrb.com/) or [StackOverflow](https://stackoverflow.com/questions/tagged/jekyll). Other resources:
189+
190+
* [Ruby 101](https://jekyllrb.com/docs/ruby-101/)
191+
* [Setting up a Jekyll site with GitHub Pages](https://jekyllrb.com/docs/github-pages/)
192+
* [Configuring GitHub Metadata](https://github.com/jekyll/github-metadata/blob/master/docs/configuration.md#configuration) to work properly when developing locally and avoid `No GitHub API authentication could be found. Some fields may be missing or have incorrect data.` warnings.
193+
194+
### Running tests
195+
196+
There are some tests for the python scripts. You can run them by running the following command in the root folder:
197+
198+
```bash
199+
python -m unittest
200+
```

‎documentation/creating-posts.md

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Creating Pages under _posts
2+
3+
## Teaching
4+
To write a course description, create a new file called `<YYYY>-<MM>-<DD>-<shorthand>.md` in the [`_posts/teaching` directory](_posts/teaching). Note that `<shorthand>` will determine the URL of the file, so choose carefully.
5+
6+
```yaml
7+
---
8+
title: "COMP XYZ - Semester YYYY" # Add course code, followed by the semester it's taught
9+
author: Reihaneh Rabbany # Name of the instructor
10+
categories:
11+
- Teaching # Used to list all posts describing a course in /teaching/
12+
tags:
13+
- Winter 2022 # Semester
14+
- Course Name # Course Name
15+
---
16+
```
17+
18+
Then, add content relevant to the course using markdown below the `---`, e.g.:
19+
20+
```markdown
21+
* **Course codes:** COMP XXX (Semester Code)
22+
* **Instructors:** XXX
23+
* **Location:** XXX
24+
* **Time:** XXX
25+
* **Course Website:** [here](url)
26+
27+
# Overview
28+
Course Overview
29+
30+
```
31+
32+
### Deleting a post
33+
34+
You may want to delete posts forever. Then, delete the file in `_posts/`. If you simply want to hide it, you can prepend the file name with `hide`. For example, to hide the file `2016-03-09-COMP-XYZ.md`, you can rename it to `hide-2016-03-09-COMP-XYZ.md`.
35+
36+
## Create a profile page
37+
38+
> [!NOTE]
39+
> *If you are having a hard time in this section, try to copy from someone else's profile and modify it.*
40+
41+
To have your own profile, you can create a new file called `<username>.md` in the [`_pages_/profiles` directory](_pages_/profiles). Note that `<username>` will determine the URL of the file, so choose carefully. You will need to add the following at the top:
42+
43+
```yaml
44+
---
45+
title: John Doe # Add your name
46+
permalink: /people/john/ # Add your username
47+
layout: archive
48+
classes:
49+
- wide
50+
- no-sidebar
51+
---
52+
```
53+
54+
Then, you can add any content you like using markdown:
55+
56+
```markdown
57+
Welcome to John Doe's personal profile!
58+
59+
## Publications
60+
61+
<div>
62+
{% include posts-publication.html taxonomy="Publications" author="John Doe" %}
63+
</div>
64+
65+
## Teaching
66+
67+
<div>
68+
{% include posts-category.html taxonomy="Teaching" author="John Doe" %}
69+
</div>
70+
71+
## Blog posts
72+
73+
<div>
74+
{% include posts-category.html taxonomy="Blog" author="John Doe" %}
75+
</div>
76+
77+
## Contact
78+
79+
Here's how to contact John Doe: ...
80+
```
81+
82+
Note that by using `{% include posts-publication.html taxonomy="Publications" author="John Doe" %}`, you can display all posts about publications by filtering for "John Doe" in the `names` field of each publication. If you choose `{% include posts-category.html taxonomy="Teaching" author="John Doe" %}`, you can display all posts about teaching instead, and `taxonomy="Blog"` will display all posts about blog posts. Note that `posts-publication.html` and `posts-category.html` are special html files in `_includes/` that generate a list of post following a specific format. That's a Jekyll feature and is considered as an advanced feature, so you don't have to worry and can just directly use it like above.
83+
84+
Then, you can update `_data/authors.yml` to include a link to your profile page, e.g.:
85+
86+
```yaml
87+
John Doe:
88+
name: "John Doe"
89+
# ...
90+
links:
91+
- label: "Page"
92+
url: "/people/siva"
93+
icon: "fas fa-fw fa-user"
94+
- label: "Github"
95+
url: "..."
96+
#...
97+
```

‎documentation/members.md

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
## Add new member profile
2+
3+
> [!NOTE]
4+
> *Have you tried using issue forms? They should be faster and easier for most of the (simpler) scenarios. This section is only if you need to make custom changes not covered by the forms.*
5+
6+
Navigate to [_data/authors.yml](./_data/authors.yml) and add the desired information at the end of the file. It has to follow the following template:
7+
8+
```yaml
9+
John Doe: # Your full name; this will be used for post `author`
10+
name: "John Doe"
11+
role: "PhD" # One of: "Faculty", "Adjunct Faculty", "Postdoc", "PhD", "Master", "Undergraduate", "Intern"
12+
avatar: "/assets/images/bio/placeholder/default.jpg" # Path to image of you (place in assets/images/bio)
13+
advisor: "John Doe Sr." # The advisor or advisors of the new member
14+
date: "Sep 2030" # Start date. Must be in the "MMM YYYY" format, or "Fall"/"Winter".
15+
bio: "Just some cool student" # Describe the new member (optional)
16+
note: "Co-advised by Amasa L." # Additional notes (optional)
17+
alumni: false # Whether the new member is an alumni
18+
new_role: "Professing at Leland Junior S. University" # If an alumni, their new role
19+
auto_update_publications: false. # Whether to automatically look for new papers published by this author every 2 weeks
20+
links:
21+
- label: "Website"
22+
url: "https://john-doe.github.io/" # Link to website
23+
- label: "GitHub"
24+
url: "https://github.com/john-doe" # Link to Github profile
25+
- label: "Twitter"
26+
url: "https://twitter.com/john-doe" # Link to Twitter profile
27+
- label: "Scholar"
28+
icon: "fas fa-fw fa-graduation-cap" # Font Awesome icon
29+
url: "https://scholar.google.com/citations?user=<user_id>" # Link to Google Scholar profile
30+
```
31+
32+
This will look like this:
33+
34+
![Demo of user profile](.github/images/demo-profile.jpg)
35+
36+
`John Doe`: Replace `John Doe` with your full name. This will be what you will use when writing a blog post or a publication abstract, and is required for certain automatic forms. Note that if someone already has the same name, you can append your start date, but that might break some automations.
37+
38+
`avatar`: Note that the `avatar` field links to an image located in `assets/images/bio`. You will need to upload the image to the repository before it shows up. Make sure you choose a picture in `jpg` (to save space), an aspect ratio of 1:1, resolution of about 300x300, and mainly centered around the face. In a hurry, you may use the default image.
39+
40+
`icon`: An icon that can be found in the [Font Awesome v5 free library](https://fontawesome.com/v5/search?m=free). V6 (most recent) will not work. In the HTML snippet, copy the string after `class=`. For example, if your string is `<i class="fab fa-accessible-icon"></i>`, then only copy `"fas fa-graduation-cap"` for the Google Scholar icon. This is optional only when `label` is "Website", "GitHub", "LinkedIn", or "Twitter". Otherwise, that link will not appear under your name in `/people/`.
41+
42+
### Modifying a member's profile
43+
44+
Has a member graduated? Does a member wish to have a new profile picture or bio? You can modify the profile of a member by editing the `_data/authors.yml` file.
45+
46+
### Deleting a member
47+
48+
If you wish to delete a member (e.g. added by mistake, duplicates, etc.) you can directly delete their "block" (everything indented after their name) in the `_data/authors.yml` file.

0 commit comments

Comments
 (0)