Skip to content

Commit 121d3d0

Browse files
mmcinnestaylormmcinnestaylor
committed
Merge branch 'additional-docs'
2 parents e8e1e90 + 968bf2d commit 121d3d0

21 files changed

+706
-216
lines changed

‎docs/_config.yml

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ favicon_ico: "/assets/images/favicon.ico"
1010

1111
# Enable or disable the site search
1212
# Supports true (default) or false
13-
search_enabled: false
13+
search_enabled: true
1414
search:
1515
# Split pages into sections that can be searched individually
1616
# Supports 1 - 6, default: 2
@@ -44,7 +44,7 @@ aux_links:
4444
- "//github.com/mmcinnestaylor/Programming-Contest-Suite"
4545

4646
# Makes Aux links open in a new tab. Default is false
47-
#aux_links_new_tab: true
47+
aux_links_new_tab: true
4848

4949
# Back to top link
5050
back_to_top: true
@@ -68,6 +68,52 @@ callouts:
6868
title: Warning
6969
color: red
7070

71+
# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
72+
mermaid:
73+
# Version of mermaid library
74+
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
75+
version: "11.2.0"
76+
# Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
77+
# See also docs/ui-components/code
78+
# To load mermaid from a local library, also use the `path` key to specify the location of the library; e.g.
79+
# for (v10+):
80+
# path: "/assets/js/mermaid.esm.min.mjs"
81+
# for (<v10):
82+
# path: "/assets/js/mermaid.min.js"
83+
# Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
84+
85+
# External navigation links
86+
nav_external_links:
87+
- title: Django Documentation
88+
url: https://docs.djangoproject.com/en/4.2/
89+
hide_icon: false # set to true to hide the external link icon - defaults to false
90+
opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
91+
- title: Celery Documentation
92+
url: https://docs.celeryq.dev/en/v5.3.1/
93+
hide_icon: false # set to true to hide the external link icon - defaults to false
94+
opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
95+
- title: Flower Documentation
96+
url: https://flower.readthedocs.io/en/latest/
97+
hide_icon: false # set to true to hide the external link icon - defaults to false
98+
opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
99+
- title: MariaDB Documentation
100+
url: https://mariadb.com/kb/en/documentation/
101+
hide_icon: false # set to true to hide the external link icon - defaults to false
102+
opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
103+
- title: Redis Documentation
104+
url: https://redis.io/docs/latest/get-started/
105+
hide_icon: false # set to true to hide the external link icon - defaults to false
106+
opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
107+
- title: RabbitMQ Documentation
108+
url: https://www.rabbitmq.com/docs
109+
hide_icon: false # set to true to hide the external link icon - defaults to false
110+
opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
111+
- title: Docker Documentation
112+
url: https://docs.docker.com/
113+
hide_icon: false # set to true to hide the external link icon - defaults to false
114+
opens_in_new_tab: true # set to true to open this link in a new tab - defaults to false
115+
116+
71117
plugins:
72118
- jekyll-seo-tag
73119
- jekyll-github-metadata

‎docs/about.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: About
3+
layout: about
4+
nav_order: 2
5+
---
6+
7+
# About
8+
9+
The Programming Contest Suite (PCS) is a set of tools for running [ICPC](https://icpc.global) style programming contests hosted by the [Association for Computing Machinery Florida State University Student Chapter](https://fsu.acm.org) (ACM@FSU). The suite is designed to work alongside a [DOMjudge](https://www.domjudge.org/) jury system by facilitating contest registration and management, generating contestant data files required by DOMjudge, and processing contest results generated by DOMjudge.
10+
11+
## Motivation
12+
13+
This project is the successor to [FSU-ACM/Contest-Server](https://github.com/FSU-ACM/Contest-Server), a Flask based ACM@FSU Programming Contest registration server created by [Andrew Sosa](https://github.com/andrewsosa). The PCS was intended to:
14+
15+
1. Address the limitations of FSU-ACM/Contest-Server
16+
2. Enhance and ease engagement with administrators, contestants, volunteers and university faculty
17+
3. Provide a codebase maintainable by student, and often newer, developers
18+
19+
## Development
20+
21+
The project was initially developed between early 2020 and its first live deployment for the 2021 Fall Programming Contest. It has since been under active development and maintenance, with management of the project being transferred to ACM@FSU in early 2024.
22+
23+
## The Contest
24+
25+
The ACM@FSU Programming Contest is held each Spring and Fall semester at [Florida State University](https://www.fsu.edu). It routinely attracts 300-500 contestants, many of whom are FSU Computer Science students, and is actively supported by Computer Science Department faculty.

‎docs/assets/images/account_registration.png

56.4 KB
Loading

‎docs/configuration.md

Lines changed: 0 additions & 91 deletions
This file was deleted.

‎docs/deployment/configuration.md

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Configuration
3+
layout: default
4+
parent: Deployment
5+
nav_order: 2
6+
---
7+
8+
# Configuration
9+
10+
The PCS's main settings file[^1] and Flower settings file[^2] can be modified directly or with values specified through the use of environment variables. Environment variable values may be passed directly or as the contents of a file. In the latter case, the full path of the file should be passed as a variable's value. Environment variable values may be stored and passed as [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/).
11+
12+
13+
### Default Values
14+
15+
Many of the default values used in the PCS's configuration files are designed for a Docker deployment similar to the examples in the [Docker Deployment]({{ site.url }}/deployment/docker/) section of this documentation.
16+
17+
{: .important-title }
18+
> Notation
19+
>
20+
> **(D)** debug mode `DEBUG=True`
21+
> **(P)** production mode `DEBUG=False`
22+
23+
<hr>
24+
25+
## Django
26+
27+
The following variables, located in the main settings file[^1], map to various Django settings. A link to the relevant Django documentation is provided for each variable.
28+
29+
### General
30+
31+
Variable | Default | Description
32+
---|---|---
33+
SECRET_KEY | a long string[^3] | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-SECRET_KEY)
34+
DEBUG | False | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-DEBUG)
35+
ALLOWED_HOSTS | [] | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#allowed-hosts)
36+
TIME_ZONE | America/New_York | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#std-setting-TIME_ZONE)
37+
38+
39+
### Cache
40+
41+
Variable | Default | Description
42+
---|---|---
43+
CACHE_LOCATION | redis://redis:6379/0 | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#location)
44+
CACHE_TIMEOUT | **(D)** 0<br>**(P)** 300 | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#timeout)
45+
46+
47+
### Database
48+
49+
Variable | Default | Description
50+
---|---|---
51+
SQL_HOST | mariadb | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#host)
52+
SQL_PORT | 3306 | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#port)
53+
SQL_DATABASE | contestsuite | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#name)
54+
SQL_USER | contestadmin | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#user)
55+
SQL_PASSWORD | seminoles1! | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#password)
56+
SQL_TIMEZONE | America/New_York | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#time-zone)
57+
58+
59+
### Email
60+
61+
Variable | Default | Description
62+
---|---|---
63+
EMAIL_BACKEND | **(D)** `django.core.mail.backends.console.EmailBackend`<br>**(P)** `django.core.mail.backends.smtp.EmailBackend` | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#email-backend)
64+
EMAIL_HOST | None | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#email-host)
65+
EMAIL_PORT | 587 | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#email-port)
66+
EMAIL_HOST_USER | None | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#email-host-user)
67+
EMAIL_HOST_PASSWORD | None | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#email-host-password)
68+
EMAIL_USE_SSL | False | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#email-use-ssl)
69+
EMAIL_USE_TLS | False | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#email-use-tls)
70+
DEFAULT_FROM_EMAIL | acm@cs.fsu.edu | [Docs](https://docs.djangoproject.com/en/4.2/ref/settings/#default-from-email)
71+
72+
## Celery
73+
74+
The following variables, located in the main settings file[^1], map to various Celery settings. A link to the relevant Celery documentation is provided for each variable.
75+
76+
Variable | Default | Description
77+
---|---|---
78+
CELERY_BROKER | amqp://rabbitmq:5672 | [Docs](https://docs.celeryq.dev/en/stable/userguide/configuration.html#std-setting-broker_url)
79+
CELERY_BACKEND | redis://redis:6379/1 | [Docs](https://docs.celeryq.dev/en/stable/userguide/configuration.html#std-setting-result_backend)
80+
CELERY_TIMEZONE | America/New_York | [Docs](https://docs.celeryq.dev/en/stable/userguide/configuration.html#std-setting-timezone)
81+
82+
## Celery Beat
83+
84+
The following variables, located in the main settings file[^1], map to various Celery Beat settings. A link to the relevant Celery Beat documentation is provided for each variable.
85+
86+
Variable | Default | Description
87+
---|---|---
88+
CELERY_BEAT_SCHEDULE | `{'cleanup-lfg-rosters': {'task': 'lfg.tasks.cleanup_lfg_rosters', 'schedule': 600.0,}, 'scrape-discord-members': {'task': 'lfg.tasks.scrape_discord_members', 'schedule': 1800.0,}, 'verify-lfg-profiles': { 'task': 'lfg.tasks.verify_lfg_profiles', 'schedule': 600.0,},}` | [Docs](https://docs.celeryq.dev/en/stable/userguide/configuration.html#std-setting-beat_schedule)
89+
90+
## Flower
91+
92+
The following variables, located in the Flower settings file[^2], map to various Flower settings. A link to the relevant Flower documentation is provided for each variable.
93+
94+
Variable | Default | Description
95+
---|---|---
96+
FLOWER_BROKER_API | http://rabbitmq:15672/api/vhost | [Docs](https://flower.readthedocs.io/en/latest/config.html#broker-api)
97+
FLOWER_USER **(P)** | contestadmin | [Docs](https://flower.readthedocs.io/en/latest/config.html#basic-auth)
98+
FLOWER_PASSWORD **(P)** | seminoles1! | [Docs](https://flower.readthedocs.io/en/latest/config.html#basic-auth)
99+
FLOWER_COOKIE_KEY **(P)** | None | [Docs](https://flower.readthedocs.io/en/latest/config.html#cookie-secret)
100+
FLOWER_URL_PREFIX **(P)** | flower | [Docs](https://flower.readthedocs.io/en/latest/config.html#url-prefix)
101+
102+
## Discord
103+
104+
The following variables, located in the main settings file[^1], map to various PCS specific settings required for integration with Discord.
105+
106+
Variable | Default | Description
107+
---|---|---
108+
ANNOUNCEMENT_WEBHOOK_URL | None | URL of Discord server's announcement channel webhook |
109+
BOT_CHANNEL_WEBHOOK_URL | None | URL of Discord server's bot command channel webhook |
110+
GUILD_ID | 0 | Discord server's Guid ID |
111+
SCRAPE_BOT_TOKEN | None | Discord bot token required by the LFG helper bot |
112+
113+
## Misc
114+
115+
The following variables, located in the main settings file[^1], map to miscellaneous PCS specific settings. A link to relevant documentation is provided for each variable.
116+
117+
Variable | Default | Description
118+
---|---|---
119+
DOMJUDGE_URL | https://domjudge.cs.fsu.edu/public | Full URL of the DOMjudge server. Used for PCS homepage contest server status card.
120+
PCS_DOCS_URL | https://mmcinnestaylor.github.io/Programming-Contest-Suite | Base URL of the project's documentation website. Used to link registration guide and other manuals.
121+
HASHID_FIELD_SALT | a long string[^4] | [Docs](https://github.com/nshafer/django-hashid-field#hashid_field_salt) The `django-hashid-field` library is used to hash sensitive PCS database model fields.
122+
GTAG | None | [Google Analytics site tag](https://support.google.com/analytics/answer/12002338?hl=en)
123+
124+
[^1]: `Programming-Contest-Suite/src/contestsuite/settings.py`
125+
[^2]: `Programming-Contest-Suite/src/contestsuite/flowerconfig.py`
126+
[^3]: `86@j2=z!=&1r_hoqboog1#*mb$jx=9mf0uw#hrs@lw&7m34sqz`
127+
[^4]: `0s97rx*t4%68jell&lw3^)97o*kr*+*2o^(76q)ix+ilc!4ax#`

0 commit comments

Comments
 (0)