Skip to content

Commit c4c6621

Browse files
david-yz-liudavid-yz-liu
authored
Added documentation to this repo (#8022)
* Documentation moved from https://github.com/MarkUsProject/Wiki. * We now use Jekyll to build the documentation pages. * Added markus:docs Rake task to build the documentation for production.
1 parent 80b635f commit c4c6621

288 files changed

Lines changed: 8838 additions & 12 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.dockerfiles/Dockerfile‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,8 +102,9 @@ RUN mkdir -p /bundle \
102102
/app/tmp \
103103
/app/node_modules \
104104
/app/log \
105-
/app/venv && \
106-
chown -R ${USER}:${USER} /bundle /app
105+
/app/venv \
106+
/jekyll && \
107+
chown -R ${USER}:${USER} /bundle /app /jekyll
107108

108109
USER $USER
109110

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,6 @@
77

88
</details>
99

10-
<details>
11-
<summary>Associated <a href="https://github.com/MarkUsProject/Wiki">documentation repository</a> pull request (if applicable)</summary>
12-
13-
</details>
14-
1510
## Type of Change
1611
*(Write an `X` or a brief description next to the type or types that best describe your changes.)*
1712

@@ -24,6 +19,7 @@
2419
| ♻️ *Refactoring* (internal change to codebase, without changing functionality) | |
2520
| 🚦 *Test update* (change that *only* adds or modifies tests) | |
2621
| 📦 *Dependency update* (change that updates a dependency) | |
22+
| 📖 *Documentation update* (change that updates documentation) | |
2723
| 🔧 *Internal* (change that *only* affects developers or continuous integration) | |
2824

2925

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,3 +85,6 @@ compose.override.yaml
8585

8686
# Optional VSCode container configuration
8787
.devcontainer
88+
89+
# Generated documentation
90+
docs/_site/

‎Changelog.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
- Fix SVG rendering by converting base64 SVG data URIs to inline <svg> (#8001)
3030

3131
### 🔧 Internal changes
32+
- Added a Jekyll-based documentation site under `docs/`, with a Docker Compose service and a `markus:docs` rake task for production builds (#8022)
3233
- Added unique database indexes to enforce uniqueness constraints already validated at the model layer, and removed 17 single-column indexes made redundant by composite indexes (#8017)
3334
- Replaced `upload_button_control.js` with native HTML `required` validation on file upload inputs (#8016)
3435
- Upgraded to Rails v8.1.3 (#8015)

‎Gemfile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,3 +129,10 @@ end
129129
group :unicorn do
130130
gem 'unicorn'
131131
end
132+
133+
group :docs do
134+
gem 'jekyll', '~> 4.4'
135+
gem 'jekyll-relative-links'
136+
gem 'jekyll-seo-tag'
137+
gem 'just-the-docs'
138+
end

‎Gemfile.lock‎

Lines changed: 64 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ GEM
120120
regexp_parser (>= 1.5, < 3.0)
121121
xpath (~> 3.2)
122122
chunky_png (1.4.0)
123+
colorator (1.1.0)
123124
combine_pdf (1.0.31)
124125
matrix
125126
ruby-rc4 (>= 0.1.5)
@@ -180,10 +181,14 @@ GEM
180181
dry-initializer (~> 3.2)
181182
dry-schema (~> 1.14)
182183
zeitwerk (~> 2.6)
184+
em-websocket (0.5.3)
185+
eventmachine (>= 0.12.9)
186+
http_parser.rb (~> 0)
183187
erb (6.0.4)
184188
erubi (1.13.1)
185189
et-orbi (1.2.11)
186190
tzinfo
191+
eventmachine (1.2.7)
187192
exception_notification (5.0.1)
188193
actionmailer (>= 7.1, < 9)
189194
activesupport (>= 7.1, < 9)
@@ -195,6 +200,7 @@ GEM
195200
faker (3.8.0)
196201
i18n (>= 1.8.11, < 2)
197202
ffi (1.16.3)
203+
forwardable-extended (2.6.0)
198204
fugit (1.11.1)
199205
et-orbi (~> 1, >= 1.2.11)
200206
raabro (~> 1.4)
@@ -204,10 +210,14 @@ GEM
204210
glob (0.4.0)
205211
globalid (1.3.0)
206212
activesupport (>= 6.1)
213+
google-protobuf (4.35.1)
214+
bigdecimal
215+
rake (~> 13.3)
207216
hashdiff (1.2.1)
208217
highline (3.1.2)
209218
reline
210219
histogram (0.2.4.1)
220+
http_parser.rb (0.8.1)
211221
i18n (1.14.8)
212222
concurrent-ruby (~> 1.0)
213223
i18n-js (4.2.3)
@@ -230,6 +240,35 @@ GEM
230240
prism (>= 1.3.0)
231241
rdoc (>= 4.0.0)
232242
reline (>= 0.4.2)
243+
jekyll (4.4.1)
244+
addressable (~> 2.4)
245+
base64 (~> 0.2)
246+
colorator (~> 1.0)
247+
csv (~> 3.0)
248+
em-websocket (~> 0.5)
249+
i18n (~> 1.0)
250+
jekyll-sass-converter (>= 2.0, < 4.0)
251+
jekyll-watch (~> 2.0)
252+
json (~> 2.6)
253+
kramdown (~> 2.3, >= 2.3.1)
254+
kramdown-parser-gfm (~> 1.0)
255+
liquid (~> 4.0)
256+
mercenary (~> 0.3, >= 0.3.6)
257+
pathutil (~> 0.9)
258+
rouge (>= 3.0, < 5.0)
259+
safe_yaml (~> 1.0)
260+
terminal-table (>= 1.8, < 4.0)
261+
webrick (~> 1.7)
262+
jekyll-include-cache (0.2.1)
263+
jekyll (>= 3.7, < 5.0)
264+
jekyll-relative-links (0.7.0)
265+
jekyll (>= 3.3, < 5.0)
266+
jekyll-sass-converter (3.1.0)
267+
sass-embedded (~> 1.75)
268+
jekyll-seo-tag (2.9.0)
269+
jekyll (>= 3.8, < 5.0)
270+
jekyll-watch (2.2.1)
271+
listen (~> 3.0)
233272
js-routes (2.3.7)
234273
railties (>= 5)
235274
sorbet-runtime
@@ -238,10 +277,20 @@ GEM
238277
jsbundling-rails (1.3.1)
239278
railties (>= 6.0.0)
240279
json (2.19.8)
280+
just-the-docs (0.12.0)
281+
jekyll (>= 3.8.5)
282+
jekyll-include-cache
283+
jekyll-seo-tag (>= 2.0)
284+
rake (>= 12.3.1)
241285
jwt (2.10.3)
242286
base64
243287
kgio (2.11.4)
288+
kramdown (2.5.2)
289+
rexml (>= 3.4.4)
290+
kramdown-parser-gfm (1.1.0)
291+
kramdown (~> 2.0)
244292
language_server-protocol (3.17.0.5)
293+
liquid (4.0.4)
245294
listen (3.9.0)
246295
rb-fsevent (~> 0.10, >= 0.10.3)
247296
rb-inotify (~> 0.9, >= 0.9.10)
@@ -258,6 +307,7 @@ GEM
258307
net-smtp
259308
marcel (1.1.0)
260309
matrix (0.4.2)
310+
mercenary (0.4.0)
261311
mini_mime (1.1.5)
262312
mini_portile2 (2.8.9)
263313
minitest (6.0.6)
@@ -289,6 +339,8 @@ GEM
289339
parser (3.3.7.4)
290340
ast (~> 2.4.1)
291341
racc
342+
pathutil (0.16.2)
343+
forwardable-extended (~> 2.6)
292344
pdf-core (0.10.0)
293345
pg (1.6.3)
294346
pghero (3.8.0)
@@ -452,6 +504,10 @@ GEM
452504
rufus-scheduler (3.9.2)
453505
fugit (~> 1.1, >= 1.11.1)
454506
rugged (1.9.0)
507+
safe_yaml (1.0.5)
508+
sass-embedded (1.101.0)
509+
google-protobuf (~> 4.31)
510+
rake (>= 13)
455511
securerandom (0.4.1)
456512
selenium-webdriver (4.35.0)
457513
base64 (~> 0.2)
@@ -480,8 +536,8 @@ GEM
480536
tilt (~> 2.0)
481537
sorbet-runtime (0.6.13266)
482538
stringio (3.2.0)
483-
terminal-table (4.0.0)
484-
unicode-display_width (>= 1.1.1, < 4)
539+
terminal-table (3.0.2)
540+
unicode-display_width (>= 1.1.1, < 3)
485541
thor (1.5.0)
486542
tilt (2.6.1)
487543
timecop (0.9.10)
@@ -491,9 +547,7 @@ GEM
491547
bigdecimal (~> 3.1)
492548
tzinfo (2.0.6)
493549
concurrent-ruby (~> 1.0)
494-
unicode-display_width (3.1.4)
495-
unicode-emoji (~> 4.0, >= 4.0.4)
496-
unicode-emoji (4.0.4)
550+
unicode-display_width (2.6.0)
497551
unicorn (6.1.0)
498552
kgio (~> 2.6)
499553
raindrops (~> 0.7)
@@ -504,6 +558,7 @@ GEM
504558
addressable (>= 2.8.0)
505559
crack (>= 0.3.2)
506560
hashdiff (>= 0.4.0, < 2.0.0)
561+
webrick (1.9.2)
507562
websocket (1.2.11)
508563
websocket-driver (0.8.1)
509564
base64
@@ -544,9 +599,13 @@ DEPENDENCIES
544599
i18n
545600
i18n-js
546601
i18n-tasks
602+
jekyll (~> 4.4)
603+
jekyll-relative-links
604+
jekyll-seo-tag
547605
js-routes
548606
jsbundling-rails
549607
json
608+
just-the-docs
550609
jwt
551610
listen
552611
machinist (< 3)

‎compose.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,20 @@ services:
119119
ports:
120120
- 6379
121121

122+
docs:
123+
<<: *app
124+
working_dir: /app/docs
125+
command: bundle exec jekyll serve --host 0.0.0.0 --livereload
126+
ports:
127+
- "4000:4000"
128+
- "35729:35729"
129+
volumes:
130+
- bundle:/bundle
131+
- .:/app:cached
132+
- jekyll_data:/jekyll
133+
depends_on: []
134+
profiles: ["docs"]
135+
122136
webpack:
123137
<<: *app
124138
image: markus-dev-webpack:1.3.0
@@ -143,6 +157,7 @@ volumes:
143157
tmp:
144158
log:
145159
python:
160+
jekyll_data:
146161

147162
networks:
148163
markus_dev:

‎docs/_config.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
destination: /jekyll/site
2+
cache_dir: /jekyll/cache
3+
4+
title: MarkUs Docs
5+
description: Documentation for MarkUs — a web-based tool for the submission and grading of student programming assignments.
6+
theme: just-the-docs
7+
favicon_ico: "/assets/images/favicon.ico"
8+
color_scheme: markus
9+
color_scheme_toggle: true
10+
11+
sass:
12+
quiet_deps: true
13+
silence_deprecations:
14+
- import
15+
- global-builtin
16+
- color-functions
17+
18+
plugins:
19+
- jekyll-seo-tag
20+
- jekyll-relative-links
21+
22+
nav_external_links:
23+
- title: GitHub
24+
url: https://github.com/MarkUsProject/Markus
25+
26+
defaults:
27+
- scope:
28+
path: ""
29+
values:
30+
layout: "default"

‎docs/_sass/color_schemes/markus.scss‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
// MarkUs light color scheme for just-the-docs
2+
// Based on the MarkUs application color palette
3+
4+
$color-scheme: light;
5+
6+
// Backgrounds
7+
$body-background-color: #fff;
8+
$sidebar-color: #e8f4f2; // --background_support
9+
$code-background-color: #f5f6fa;
10+
$table-background-color: #fff;
11+
$search-background-color: #fff;
12+
$feedback-color: #cee3ea; // --primary_two (replaces darken() call)
13+
14+
// Text
15+
$body-text-color: #464646; // --line
16+
$body-heading-color: #245185; // --primary_one
17+
$search-result-preview-color: #464646;
18+
19+
// Links and navigation
20+
$link-color: #245185; // --primary_one
21+
$nav-child-link-color: #464646;
22+
23+
// Buttons
24+
$base-button-color: #cee3ea; // --primary_two
25+
$btn-primary-color: #32649b; // --sub_menu

‎docs/_sass/custom/custom.scss‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Flush nav items to the left edge of the sidebar
2+
.nav-list-link {
3+
padding-left: 0;
4+
5+
@include mq(md) {
6+
padding-left: 0;
7+
}
8+
}
9+
10+
.nav-list .nav-list {
11+
padding-left: 0;
12+
}
13+
14+
// Active nav item: left border accent + stronger background
15+
.nav-list-link.active {
16+
background-color: $base-button-color; // #cee3ea (--primary_two)
17+
border-left: 3px solid $link-color; // #245185 (--primary_one)
18+
font-weight: 600;
19+
}

0 commit comments

Comments
 (0)