Class pages and courses

Three addresses, three purposes

Publishing does not close the room. To leave the group read-only access, click “End class” in the room (“End the class” in the panel).

Publish a class

Materials are chosen on the Class page screen. There are three ways to it:

• after the class ends, if the room is in a course and has no page yet: the room shows a “Class finished” window; Choose materials → opens the screen in a new tab, and “Not now” closes the window until the next time the class is ended;
• from the strip of a finished class in the room: the link “Publish materials →”, which becomes “Class page →” after the first publish. Only the teacher sees it, and every room has it, in a course or not;
• from the panel: Class page… in the class menu under “Classes”, or in a row's menu on the course page.

1. Check the ticks under “Notebooks” and “Files”. Colloq sets them itself and writes the reason next to every unticked row (see below).
2. Rename materials if needed. A notebook's name becomes its tab (“Lecture”, “Seminar”); Markdown text (.md) opens as a tab too, with its own table of contents; a PDF's name becomes the label of its link; data, code and folders keep their room path, because the code refers to it. The ↑↓ arrows change the order of the notebooks.
3. If a “Check” section appears, look at every warning and tick “Checked — publish as it is”.
4. Click Publish. The screen shows the address of the finished page with “Copy link” and “Open”. Open it the way a student will.

A page holds up to 24 materials and up to 200 MB in total, and each file can be at most the server's upload limit (50 MB by default). A folder is one material however many files it holds (up to 1,000). The screen shows how much is used: “Page: 10.8 MB of 200 MB”.

Publishing again — “Update the page” on this screen or in a course row's menu — rebuilds the page at the same link from what is in the room now. Updating never brings a withdrawn page back: its course row has no such item, and on the Class page screen the button says “Publish again”. If a ticked file is gone, has grown over the limit, or the page is full, the screen names it under “Left off the page”. A folder is only ever left off whole: half a dataset is worse than none.

What is ticked from the start

Every notebook is ticked except empty ones and those that look like someone else's or private. PDFs are ticked unless one of the reasons below applies: they are usually the slides. Data, code and text files are ticked only when a notebook refers to them (the row says “used in seminar.ipynb”) and they are small: data up to 20 MB, code and text up to 200 KB. A README at the top of the room is ticked even without a reference.

The ticks are suggestions, not decisions: any unticked row can be ticked, except an empty notebook and a file over the upload limit. The rules lean towards leaving things out: adding a file is one click, while a link already handed out cannot be taken back.

Notebooks and files that appeared after the previous publish are marked “new” and left unticked: neither chosen nor knowingly left out.

Folders: data, modules and pictures

A top-level folder of the room — data/, scripts/, assets/ — is chosen whole, as one row: “data/ · 15 files · 25 MB”. On the class page it is one row too, “Data · 15 files · 25 MB”, and downloads as one ZIP with the folder inside. This is how the modules the notebooks import (from scripts import case_cian as cian) and the pictures in their text end up beside them, at the same paths as in the room.

A folder is ticked from the start when something being published uses it: a ticked notebook reads a file in it or imports it as a package (“read in lecture.ipynb and scripts/eda_tools.py”, “imported in lecture.ipynb”), code in another ticked folder reads it, or the notebooks' text shows pictures from it. An unticked notebook, such as solutions.ipynb, ticks no folder.

Inside a folder the rules from the table above apply, except “not mentioned in the notebooks”: drafts starting with «_», answers, a participant's name anywhere in the path (hw/zuev_akim/model.py), run outputs and files over the upload limit stay in the room. So do files the check cannot read: those named like a key and files of an unknown kind. Data and pictures go at any size within the limit. __init__.py always goes, and a package's «_» module goes when the published code imports it (from ._utils import plot): without it the package does not import after unpacking.

The what is inside ▾ link under the row lists every file with a tick, and a reason next to those that stay in the room. The ticks can be changed: tick _utils.py or submission_example.csv, untick holdout.csv. Only a file over the upload limit cannot be ticked. If by the rules nothing in a folder can go out, tick the file you need in its contents, and the folder is ticked with it.

A folder with more than 1,000 files, such as lib/ after pip install --target, is not published: “over 1000 files”.

If the server is rolled back to 0.13 or an earlier release, at startup it deletes from the page store the files only folders refer to. Back on the current release, Colloq puts them back at startup from the room when the room still has the same bytes; a folder it cannot restore that way is taken off its page, with a line in the log. The folder stays chosen: “Update the page” or the next end of class brings it back from the room.

The check before publishing

A room's address is the right to write into it, so it is always removed from cells and output, without asking: the path /workspace/<room>/data.csv in a traceback becomes data.csv. The screen only reports it: “The room's address was removed from 2 cells; it will not be on the page.”

Everything else Colloq does not fix but shows under “Check”:

• “Looks like an API key” — in a cell, its output or a ticked file, with the notebook and the cell number or the file name, and the key, partly masked;
• “Looks like a student's name” — the full name of someone in the class in a cell, its output, a plotly chart or a ticked file; a first name on its own does not count;
• “The room's address is in …” — a text file is published as it is, and the address in it is not changed.

Code, text and data files up to 2 MB are checked the same way as cells: a utils.py with a key, a kaggle.json or a class list in a CSV goes onto the page byte for byte, so it is shown under “Check” rather than fixed.

A string that looks like a key may be a placeholder the lesson is about, and a full name may be a scientist's, so the teacher decides. “Open in the room” leads to the cell: fix it there, or tick “Checked — publish as it is”. Until it is ticked, the publish button stays disabled. The confirmation is remembered for that finding; a new key or name is a new finding.

Updating every time the class ends

The choice is made once; after that, ending the class is enough. Update the page every time the class is ended is on by default: the ticks are remembered, and each time this room's class is ended again, Colloq rebuilds the page by itself.

• Queued cells keep running after the class ends, so Colloq first waits for them to finish, for at most two minutes. The teacher in the room sees “The page will update once the cells finish running”, then “Class page updated · 4 materials”.
• New notebooks, files and folders are not added by themselves: next time they wait on the screen marked “new”. A ticked notebook that was deleted from the room is skipped.
• A ticked folder is read again whole: a new file in data/ goes onto the page by the folder rules and passes the same check. Files whose tick in “what is inside” was changed by hand keep that decision.
• If something new turns up in the check — a key, a name, or the room's address in a file — the page stays as it was, and the room shows “The page was not updated: …” with a “Review” button.
• “Resume class” never touches the page. If the class is resumed, the page withdrawn or the option switched off while the cells finish, there is no update, and its notice goes away.

When the class is ended from the panel, the panel says the same in short: “The class is over · the class page is being updated.” To stop the page from changing by itself, untick the option and publish again.

What becomes public

The Class page screen shows the same list above the publish button.

A name, a key or personal data already written in code or output becomes part of the page, and the check does not catch everything. Look through the ticked notebooks yourself.

The page asks search engines not to index it. This is not access control: anyone who has the link can open the page and pass it on. When many people download one class's archive at once, the server sends it to three at a time (and six across the whole server), and the rest wait their turn: the download simply starts a little later. Only after more than a minute of waiting does “Too many downloads — try again in a minute” come back. A download that stands still for a minute is cut off and frees its place.

The class day

Every class in a course has a day — a calendar date in the server's time zone. The course page uses it to sort classes into months, draw the “today” line and decide which class was the previous one and which is next. It is the day of the course row, not the publication date: materials put up a week before the class still sit on its day.

The day appears by itself:

• from the plan: a row has a “Class day” field, and a new row defaults to the previous row's day plus a week. A room created from a row, or assigned to it, takes over the day along with the topic;
• from attendance: on the upgrade to this release, plan rows whose week text names a single day (“Sun, Sep 6”, “06.09”) got that day, and classes already held got the day the most students joined the room, otherwise the day the class was ended;
• when the class ends: a row without a day gets the day the class was ended.

A week written as text (“31 Aug – 6 Sep”) is shown until a day is set. To correct a day, use the course: the row's menu → “Edit the row…”. For a page outside a course, the day is the “Class day” field on the Class page screen; by default it is the day the class was ended, otherwise the day of the first publish.

Build a course

In the panel, open Courses and create a course: its title, description and address. The term plan is typed in with “+ Planned topic”: the topic is required, and next to it are “Class day”, “What it is about — a sentence or two” and the “A break — no number” box for holidays. “Add to plan” or Enter saves the row, and the form stays open for the next one.

The easiest way to create a class's room is from the course: “Create a room” on a plan row, or the “Course class” field on the “New class” screen, where the open rows of every course are listed nearest first. The room takes its row, with the topic, day and summary already there. An existing room goes into a row with “Assign class”, and “+ Add a class” puts it at the end of the course. Students see the row's topic, or for a room added without a plan row, its name; “Title for students” under “Edit the row…” sets a title of its own.

The “Page” column of the course table shows where each class stands: “planned”, “page · 4 materials”, “before class · 2 materials” when the materials went up early, “withdrawn”, and for a past class with no page the warning “The class is over and has no page — Publish…”. Under the page address, Edit the materials opens the class page, where materials are added, removed and published again. The row's menu has “Class page…”, “Update the page”, “Page address…”, “Open as a student”, “Hide from the course” and “Take the page down”.

Give the group the /c/… address once. On the course page a student sees:

• the “now” blocks: “Today · Sun, 4 Oct” or “Next · Sun, 4 Oct · in 2 days”, and “Previous class · Sun, 20 Sep”, with links to the materials and the archive. Before the course starts the top block says “First class”, after it ends “Last class”, and the header adds “course finished”;
• the “Classes” list in course order, with month labels (“September”, “January 2027”) and a “Today” line between past and future classes. A class with a page has a link and a summary of what is on it: “lecture · seminar · slides · data”; a future class shows its day; on the day itself it says “today · materials after the class”; materials put up early are labelled “materials before the class”;
• breaks without a number: “Holidays — no classes”;
• classes more than three months ahead folded under “show the whole plan”, when there are more than eight of them.

“Today” is the server's day, not the student's browser's. If a past class has no page, the course says “No materials yet.” and offers the latest published materials. The course page does not reveal room addresses, except for the “Enter the room” button on the day of a class (see below).

Entering the room from the page

The room keeps what the page does not have: the edit history, the marks and the questions to the oracle with their answers. To make it easy to get back to them, the class page has a Class room block under the materials with a “Go to the room” button; on a phone it is a “Class room” row under the archive button. On the day of a class, while it is on, the “Today” block of the course page becomes “Today · Sun, 4 Oct · class in progress” with an Enter the room button.

Who sees the way in is chosen by the teacher on the Class page screen, under “Entering the room from the page”. Once the page exists, the choice is saved at once and does not rebuild the page; before the first publish it goes out with it:

The button leads into the room itself, and the room's rules apply there: while the class is on, whoever comes in works as an ordinary participant; after it ends, they can only read. A course row without a page lets people in under the “Everyone” rule: during a class, anyone with the course link can enter the room. A withdrawn page or a deleted room has no way in for anyone, teachers included. Pages carried over from earlier releases also lead into the room under the “Everyone” rule; another choice is kept from their next publish from this screen.

Pages published in 0.13 keep the choice saved back then: “Participants”, unless the teacher changed it. To open their room to everyone, switch the way in to “Everyone” by hand.

Under “Participants”, another browser or a private window shows no button, and a newcomer gets the room link from the teacher.

Short and previous addresses

A class page or course can get a name made of lowercase Latin letters, digits and hyphens, 3 to 64 characters long, starting and ending with a letter or digit. For example, /c/python-autumn. The first publish from a course with such a name gets an address like /p/ml-strong-04 (the course name and the class number) if it is free; renumbering the rows never changes it afterwards. A page's address can be changed at any time — on the Class page screen, or with “Page address…” in a course row's menu.

After a rename, the previous address keeps leading to the current material and stays reserved. Releasing the previous name stops the old link from working and lets the name be used again. Release it only when you are ready to change an address you have already handed out.

Take a page down or delete a room

Hide from the course in a course row's menu (and in the class menu under “Classes”, when the class is in a course) is for a class put up early, say the day before the seminar. While it is hidden, students see an ordinary plan row in its place, with its number, its day and the row's topic (or “Class 3” when it has none, never the room's name). Its /p/… page, its materials and its archive answer as if there were no such page, the class offers no “Enter the room” button, and link cards leave it out. In the panel the row says “Hidden from the course”, and the course's teachers still open the page as usual, with a note at the top, so it can be checked before it is shown. If the room sits in two courses, hiding it in one closes the page in the other too, where the row says “Hidden in another course”. “Show in the course” in the same menu brings back the row, the page and the materials as they were: nothing is taken down or rebuilt. Whoever may edit the course's rows may hide and show a class, and each change goes into the audit log.

“Take the page down” in a course row's menu (or in the class menu under “Classes”) closes the page: the link tells students the teacher took it down. “Put the page back” in the same place, or on the Class page screen, opens it again. Publishing and archiving do not change the permissions in the live room.

By default, deleting a room keeps its page; read the options in the delete confirmation carefully. The materials are stored apart from the room, so the page survives the deletion and its course row keeps leading to it. Such pages are collected on the “Courses” page under “Pages without a room”: you can withdraw them (“Withdraw page”) or bring them back (“Restore page”), and the owner can delete a withdrawn page permanently. On the Class page screen such a page keeps only its current materials: you can “Take off the page” what is not needed, its images included, but there is nothing left to add from.

Page files live in data/page-files/ and are part of the server backup; a file used on several pages is stored once. But a page does not replace a backup: it does not contain all the working files, configuration, secrets and room data.

Older pages and links

Pages published before class pages existed were turned, on the first start of the new release, into pages with one material, “Notebook”: the last published state of the notebook with its results, contents and archive. Pages no longer have steps or marked moments; the marks in the “History” panel stay in the room as restore points.

Links already handed out keep working: /p/<address>/<step number> opens the class page, and the old notebook download link leads to the download of the page's first notebook, now with its run results.

GitHub import now also takes PDF and Markdown files: slides and READMEs kept in a repository reach the room, and from there the class page.

The static export of a course into a repository (make site) is gone: course and class pages live only on your server, and an offline copy of a class is its “Download all” archive.