Merge pull request #7 from brson/master

More rust training content

rust/.gitignore

@@ -1,2 +1,2 @@
 *~
-yarn-error.log
+target/

rust/CONTRIBUTING.html

@@ -0,0 +1 @@
+index.html

rust/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+TODO organize this
+
+Every md file has a html relative symlink to index.html:
+
+`ln -s index.html CONTRIBUTING.html`
+
+The static website loads the page content from markdown dynamically,
+based on the URL of its HTML page.
+
+Project text doesn't link directly to documentation resources containing
+solutions - students should learn where to get the answers from the
+pre-requisites and lessons.
+
+Project text may include inline links to pages that offer explanatios of terms
+and concepts.
+
+Keep the project summary (the **Task**, **Goals**, etc. text) synced between
+plan.md and the project description.
+
+Common sections of project descriptions:
+
+- The project summary (directly after h1)
+- "Introduction"
+- "Project spec"
+
+Headers do not capitalize every word; words after a colon
+are capitalized:
+
+> ## Project spec
+
+> ## Lesson: Tools and good bones
+
+In projects, be clear on when the student should start hacking, and what they
+should be hacking, by writing an imperative statement. Format that command in
+italics:
+
+> <i>Use [crates.io](https://crates.io) to find the documentation
+for the `clap` crate, and implement the command line interface
+such that the `cli_*` test cases pass.</i>
+
+> _Try it now._
+
+## Developing a new section
+
+Each section provides a similar project to previous sections, while expanding
+the scope and building off of learnings from previous sections. Each project
+lends itself to being extended by the next section's project.
+
+New sections are developed in pairs, to benefit from the feedback.
+
+Approximate workflow:
+
+- Author 1 and 2 collaborate on an outline for the new section, adding it to
+  plan.md, following the format of existing sections. This includes supporting lessons
+  and readings. Submit PR.
+
+- Author 1 writes the entire project description; optionally with test cases if
+  that makes the writing easier. Add new background readings or otherwise modify
+  the section plan as needed. Submit PR. Author 2 reviews.
+
+- Author 2 writes the remaining test cases and an example solution project. Add
+  new background readings or otherwise modify the section plan as needed. Submit
+  PR. Author 1 reviews.
+
+- Author 2 makes changes to the project text for clarification, improvement,
+  scope expansion, etc. Add new background readings or otherwise modify the
+  section plan as needed. Submit PR. Author 1 reviews.
+
+##
+
+When writing a project, look for steps where the design could be specified differently,
+where there are multiple solutions, where there is deeper understanding to be gained,
+and ask questions formulated to get the reader to think more deeply.
+
+Projects should be written to take between 2 - 4 hours to implement.
+
+When writing a project, look for optional "extension" steps that teach
+additional practical subjects, but which either aren't necessary to complete the
+project or require more time and skill to implement. Extenion steps go at the
+end of a project.
+
+## Contributor notes
+
+- each md file needs an html relative symlink to index.html
+- lessons need a .slides.html symlink
+- links are generally to markdown files, not html files
+  - exception: links to slides from plan go to the hosted website
+  - all links rewritten when browsed locally
+- in markdown, write links as relative to current directory
+- keep "task", "goals", etc in project intros in sync between "plan.md" and
+  project pages
+

rust/README.md

@@ -3,16 +3,14 @@
 A training course on practical software construction in Rust.
 
 The final project in this course is a networked, persistent [key-value store]
-with multithreading, asynchronous I/O (via [tokio] and [tower]), a
-high-performance network protocol ([GRPC] via [prost] and [tower-grpc]),
-backed by a simple [LSM-tree] that the student will write themselves.
+with multithreading, asynchronous I/O (via [hyper]).
 
 Subjects covered include:
 
 - Structuring and maintaining Rust programs
 - Fun and foolproof parallel programming
-- Asyncronous programming with [futures] and [tokio]
-- High-performance networking with [GRPC] and [prost]
+- Asyncronous programming with [futures]
+- Networking with [hyper]
 - Benchmarking with [criterion] and [critcmp]
 - Robust and reliable error handling with [failure]
 - Serialization with [serde]
@@ -119,7 +117,7 @@ recommended to teach this course.
 
 ## Contributing
 
-TODO
+See [CONTRIBUTING.md].
 
 ## License
 
@@ -148,4 +146,5 @@ TODO
 [Distributed Systems in Rust]: todo
 [The Rust Book]: https://doc.rust-lang.org/book/
 [plan]: plan.md
-[serde]: todo
+[serde]: todo
+[CONTRIBUTING.md]: CONTRIBUTING.md

rust/css/style.css

@@ -4,7 +4,7 @@ nav#site-nav {
 	position: absolute;
 	top: 0px;
 	width: 100%;
-	background: #666666;
+	background: #555;
 	color: white;
 	padding: 1rem;
 	line-height: 1.5rem
@@ -20,8 +20,3 @@ nav#site-nav a:hover {
 	color: orange;
 }
 
-section#content {
-	margin: 1rem;
-	margin-top: 4.5rem; /* nav border * 2 + line-height + 1rem */
-}
-

rust/css/text.css

@@ -0,0 +1,20 @@
+/* Styles for non-slide pages */
+
+section#content {
+	margin-top: 5.5rem; /* nav border * 2 + line-height + 2rem */
+}
+
+section#content {
+	padding-left: 100px;
+	padding-right: 100px;
+}
+
+pre {
+	background-color: #555;
+	color: white;
+	padding: 1rem;
+}
+
+body {
+	margin-bottom: 5rem;
+}

rust/js/common.js

@@ -8,6 +8,8 @@ export function mdUrlFromUrl(url) {
     let mdUrl = url;
     if (url.indexOf("index.html") != -1) {
         mdUrl = url.replace("index.html", "README.md");
+    } else if (url.endsWith("/")) {
+        mdUrl = url + "README.md";
     } else if (url.indexOf(".slides.html") != -1) {
         mdUrl = url.replace(".slides.html", ".md");
     } else if (url.indexOf(".html") != -1) {

rust/js/init.js

@@ -25,6 +25,7 @@ function init() {
         contentElement: contentElement,
     };
 
+    addCssForPageType(config);
     dispatchInitForPageType(config);
 }
 
@@ -45,6 +46,19 @@ function getPageType(url) {
     return type;
 }
 
+function addCssForPageType(config) {
+    if (config.pageType === "lesson-slides") {
+        return;
+    }
+
+    let head = document.querySelector("head");
+    console.log(head);
+    let link = document.createElement("link");
+    link.setAttribute("rel", "stylesheet");
+    link.setAttribute("href", "css/text.css");
+    head.appendChild(link);
+}
+
 function dispatchInitForPageType(config) {
     let mainModule = null;
     if (config.pageType === "md") {

rust/notes.md

@@ -37,6 +37,9 @@ in the README.
   - Ana likes this
 - variable shadowing
 - DSTs
+- configuring clippy / rustfmt
+- scripting clippy / rustfmt for CI
+- CI setup
 
 ## Sources
 
@@ -51,25 +54,22 @@ in the README.
 
 ## Subjects to potentially cut
 
-- Whirlwind rust lesson
 - Parallelism section
 - Formatting lesson
 - Build time lesson
 - Collections and iterators
 
-## Contributor notes
+## Grading
 
-- each md file needs a relative symlink to index.html
-- lessons need a .slides.html symlink
-- links are generally to markdown files, not html files
-  - exception: links to slides from plan go to the hosted website
-  - all links rewritten when browsed locally
-- in markdown, write links as relative to current directory
+- automated text-based cheat detection
+- automated grading of test cases
+- automated grading of non-unit-test requirements via python script
+- how to grade freeform answers?
 
 ## TODO
 
 - do survey of other sources' subject progression
 - lessons and labs pose questions
 - have a chinese native identify and remove 'hard' words and phrases
 - mention somewhere that we're using rust 2018 only, how to verify
-- change slides.html URLS to link to the hosted file
+- change slides.html URLS to link to the hosted file