Проверять то, что курс о себе говорит — и сказать, что он есть по-английски

.github/workflows/ci.yml

@@ -68,6 +68,20 @@ jobs:
       - name: Модули ведут к своим ноутбукам
         run: python scripts/check_modules.py
 
+      # Курс девять раз называет себя «двадцать семь модулей в семи частях» --
+      # цифрами, русскими словами и английскими. Ни одно из этих мест не знает,
+      # сколько модулей на самом деле, и разойтись они могут молча. Считается
+      # здесь один раз, по каталогам и таблицам программы.
+      - name: Курс говорит о себе правду
+        run: python scripts/check_counts.py
+
+      # Теги Open Graph отдаёт шаблон, а не страница: сборка проходит и с
+      # пустым заголовком (при 404 `page` пуста), и с картинкой, которой уже
+      # нет, и с заголовком, выведенным дважды. Проверяется по собранному
+      # каталогу, поэтому шаг идёт после mkdocs build.
+      - name: У каждой страницы есть что показать, когда ей делятся
+        run: python scripts/check_social.py site
+
   ci:
     name: CI
     runs-on: ubuntu-latest

.zenodo.json

@@ -1,7 +1,7 @@
 {
   "upload_type": "lesson",
   "title": "lemma — a free course in machine learning, deep learning and reinforcement learning",
-  "description": "A complete roadmap through machine learning, neural networks, reinforcement learning and recommender systems: twenty-seven modules in seven parts, from the arithmetic of a mean to reproducing a recent paper. The central skill taught is checking a claim rather than launching a training run, so the first module covers baselines and confidence intervals before any machine learning at all. Written in Russian; the notebooks run on a CPU in seconds and are executed in CI on Linux and Windows.",
+  "description": "A complete roadmap through machine learning, neural networks, reinforcement learning and recommender systems: twenty-seven modules in seven parts, from the arithmetic of a mean to reproducing a recent paper. The central skill taught is checking a claim rather than launching a training run, so the first module covers baselines and confidence intervals before any machine learning at all. Written in Russian and English, both versions complete; the notebooks run on a CPU in seconds and are executed in CI on Linux and Windows.",
   "creators": [
     {
       "name": "Drobyshev, Denis",
@@ -19,6 +19,7 @@
     "reproducibility",
     "research-methods",
     "russian",
+    "english",
     "jupyter-notebook"
   ],
   "access_right": "open",

CITATION.cff

@@ -10,8 +10,8 @@ abstract: >-
   the arithmetic of a mean to reproducing a recent paper. The central skill
   taught is checking a claim rather than launching a training run, so the first
   module covers baselines and confidence intervals before any machine learning
-  at all. Written in Russian; the notebooks run on a CPU in seconds and are
-  executed in CI on Linux and Windows.
+  at all. Written in Russian and English, both versions complete; the notebooks
+  run on a CPU in seconds and are executed in CI on Linux and Windows.
 authors:
   - family-names: Drobyshev
     given-names: Denis
@@ -28,3 +28,4 @@ keywords:
   - reproducibility
   - research-methods
   - russian
+  - english

README.en.md

@@ -0,0 +1,112 @@
+# lemma
+
+[Русский](README.md) · **English** · [Read the course](https://drobyshevdev.github.io/lemma/en/)
+
+**A free course in machine learning, neural networks, reinforcement learning and
+recommender systems — from nothing to reading and reproducing research.**
+
+[![Site](https://img.shields.io/badge/site-drobyshevdev.github.io/lemma-4f46e5)](https://drobyshevdev.github.io/lemma/en/)
+[![CI](https://github.com/DrobyshevDev/lemma/actions/workflows/ci.yml/badge.svg)](https://github.com/DrobyshevDev/lemma/actions/workflows/ci.yml)
+[![Modules](https://img.shields.io/badge/modules-27-8A2BE2.svg)](https://drobyshevdev.github.io/lemma/en/programme/)
+[![Text: CC BY 4.0](https://img.shields.io/badge/text-CC%20BY%204.0-lightgrey.svg)](LICENSE-CONTENT)
+[![Code: MIT](https://img.shields.io/badge/code-MIT-green.svg)](LICENSE)
+
+**[Read the course →](https://drobyshevdev.github.io/lemma/en/)**
+
+## What this is
+
+A roadmap through ML, DL and RL: what to learn, in what order, why, and how to tell that
+you have actually learned it. Twenty-seven modules in seven parts, from the arithmetic of
+a mean and a variance to reproducing a recent paper as a capstone.
+
+Free and open, in full. No sign-up, no "first module free", no 24-month instalment plan.
+
+A lemma is a statement proved not for its own sake but to prove the next one. The course
+is built the same way: no module stands on its own, each one holds up what comes after.
+
+Both languages are complete — twenty-seven modules in Russian and twenty-seven in English,
+the same notebook behind each.
+
+## What is different about it
+
+Most courses teach you to train models. This one teaches you to **check claims**.
+
+The field moves through papers, and the overwhelming majority of the improvements claimed
+in them do not reproduce, dissolve under an honest comparison, or come from comparing a
+tuned method against an untuned baseline. Someone who can train a model but cannot check
+a claim cannot tell progress from noise — and builds on noise.
+
+So a module does not end with "we got accuracy 0.93" but with "we checked that the
+improvement survives a change of random seed and a comparison against an honest baseline".
+Module 1 is about exactly that, before any machine learning at all.
+
+The second difference is the tie to psychology where the tie is real: reinforcement
+learning and behavioural psychology describe the same thing twice over, and recommender
+systems are applied psychology of attention.
+
+The third is that the course is written by the people who build the tools it uses. Where
+run tracking is needed, that is `mlango`; where an agent loop with a readable trace is
+needed, `glia`; where a trained policy has to be compared against a classical baseline,
+`decisionrl`, which ships that baseline with every problem. None of the libraries is
+required: everywhere the course also shows how to do the same thing by hand.
+
+## Layout
+
+```
+docs/
+  index.en.md              landing page (laid out in overrides/home.en.html)
+  programme.en.md          all 27 modules
+  capstone.en.md           the capstone: choosing a paper, reproducing it, writing it up
+  prerequisites.en.md      what to know before starting
+  how-to-study.en.md       how to study so that it works
+  modules/                 modules, <name>.md in Russian and <name>.en.md in English
+  assets/theme.css         a dark editorial theme over mkdocs-material
+overrides/home.en.html     the landing template
+notebooks/                 notebooks, one per module, shared by both languages
+```
+
+Notebooks run top to bottom with no edits and **on a CPU in reasonable time**. Where a full
+run gives a different number, that is said outright. CI executes every notebook on Linux
+and Windows: a reader whose notebook does not run does not have the course.
+
+## Running it
+
+From any module page, through the **"open in Colab"** link next to the notebook. There is
+nothing to install: the course code imports only NumPy and Matplotlib, and Colab already
+has both. A reader who cares about one module should not have to build an environment for it.
+
+Locally, if you would rather keep everything yourself:
+
+```bash
+pip install -r requirements.txt
+mkdocs serve            # → http://127.0.0.1:8000
+jupyter lab notebooks/
+```
+
+## State
+
+All twenty-seven modules are done — both language versions, a notebook for each, CI green.
+The course can be taken end to end, from the first module to the capstone.
+
+| Part | Modules | State |
+|---|---|---|
+| I. How claims are checked | 1–4 | **complete** |
+| II. Classical ML | 5–7 | **complete** |
+| III. Neural networks | 8–11 | **complete** |
+| IV. RL and psychology | 12–16 | **complete** |
+| V. Recommender systems | 17–20 | **complete** |
+| VI. Agents | 21–23 | **complete** |
+| VII. Out to the frontier | 24–27 | **complete** |
+
+## Helping
+
+The most useful feedback is **"I got stuck here"**. If an explanation did not work, that is
+a defect in the text, not in the reader, and it needs to be known about. Open an
+[issue](https://github.com/DrobyshevDev/lemma/issues) naming the module and the place.
+
+Contribution rules — the [organisation's CONTRIBUTING.md](https://github.com/DrobyshevDev/.github/blob/master/CONTRIBUTING.md).
+
+## Licences
+
+Text and illustrations — [CC BY 4.0](LICENSE-CONTENT): take them, translate them, use them
+in your own teaching, give credit. Code in the notebooks and scripts — [MIT](LICENSE).

README.md

@@ -1,5 +1,7 @@
 # lemma
 
+**Русский** · [English](README.en.md) · [Читать курс](https://drobyshevdev.github.io/lemma/)
+
 **Бесплатный курс по машинному обучению, нейросетям, обучению с подкреплением и
 рекомендательным системам — с нуля и до умения читать и воспроизводить исследования.**
 
@@ -24,6 +26,9 @@
 следующее. Курс устроен так же: ни один модуль не стоит отдельно, каждый — опора для того,
 что идёт после.
 
+Обе языковые версии полные — двадцать семь модулей по-русски и двадцать семь по-английски,
+за каждым один и тот же ноутбук.
+
 ## Чем отличается
 
 Большинство курсов учат обучать модели. Этот учит **проверять утверждения**.

docs/programme.en.md

@@ -97,5 +97,5 @@ How to choose it, do it and write it up — a full walkthrough with a checklist
 ## In total
 
 **About 50 weeks** at ten hours a week — a year at an unhurried pace, or half a year at a
-dense one. Parts I–II (8 weeks) make sense on their own: even if you stop there, you will read
+dense one. Parts I–II (12 weeks) make sense on their own: even if you stop there, you will read
 papers more carefully than most of the people who write them.

docs/programme.md

@@ -98,5 +98,5 @@
 ## Итого
 
 **Около 50 недель** при десяти часах в неделю — год неспешно или полгода плотно. Части
-I–II (8 недель) имеют смысл сами по себе: даже если вы остановитесь на них, вы будете
+I–II (12 недель) имеют смысл сами по себе: даже если вы остановитесь на них, вы будете
 читать статьи внимательнее, чем большинство тех, кто их пишет.

overrides/home.en.html

@@ -9,11 +9,20 @@
 {% block extrahead %}
   {{ super() }}
   <style>.md-main__inner { display: none; }</style>
+{% endblock %}
+
+{# Replaces the generic tags from main.html rather than adding to them. #}
+{% block social_meta %}
   <meta property="og:type" content="website">
+  <meta property="og:site_name" content="lemma">
   <meta property="og:title" content="lemma — a roadmap through ML, DL and RL, free">
   <meta property="og:description" content="Twenty-seven modules, from the arithmetic of the mean to reproducing a fresh paper. The course teaches you to check claims, not to run training.">
   <meta property="og:url" content="https://drobyshevdev.github.io/lemma/en/">
-  <meta name="twitter:card" content="summary">
+  <meta property="og:image" content="https://drobyshevdev.github.io/lemma/assets/og.png">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="lemma — a roadmap through ML, DL and RL, free">
+  <meta name="twitter:description" content="Twenty-seven modules, from the arithmetic of the mean to reproducing a fresh paper. The course teaches you to check claims, not to run training.">
+  <meta name="twitter:image" content="https://drobyshevdev.github.io/lemma/assets/og.png">
 {% endblock %}
 
 {% block tabs %}

overrides/home.html

@@ -11,11 +11,22 @@
   {# The content block below is empty on purpose; without this the theme still
      reserves a padded, empty article between the landing and the footer. #}
   <style>.md-main__inner { display: none; }</style>
+{% endblock %}
+
+{# Replaces the generic tags from main.html rather than adding to them: this
+   page's description is written for a reader deciding whether to start, which
+   a generic one cannot be. #}
+{% block social_meta %}
   <meta property="og:type" content="website">
+  <meta property="og:site_name" content="lemma">
   <meta property="og:title" content="lemma — дорожная карта в ML, DL и RL, бесплатно">
   <meta property="og:description" content="Двадцать семь модулей: от арифметики среднего до воспроизведения свежей статьи. Курс учит проверять утверждения, а не запускать обучение.">
   <meta property="og:url" content="https://drobyshevdev.github.io/lemma/">
-  <meta name="twitter:card" content="summary">
+  <meta property="og:image" content="https://drobyshevdev.github.io/lemma/assets/og.png">
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="lemma — дорожная карта в ML, DL и RL, бесплатно">
+  <meta name="twitter:description" content="Двадцать семь модулей: от арифметики среднего до воспроизведения свежей статьи. Курс учит проверять утверждения, а не запускать обучение.">
+  <meta name="twitter:image" content="https://drobyshevdev.github.io/lemma/assets/og.png">
 {% endblock %}
 
 {% block tabs %}

overrides/main.html

@@ -0,0 +1,40 @@
+{% extends "base.html" %}
+
+{#
+  Open Graph on every page, not only on the two landings.
+
+  The theme emits none, and the landings carried hand-written tags, so all
+  fifty-four module pages shared as a bare link: no title, no description, no
+  image. The shareable unit of a course is a module -- "вот модуль про дофамин
+  и TD-обучение" -- and that was the one thing with nothing to show.
+
+  `social_meta` is its own block so a landing can replace these rather than
+  append to them: appending would emit og:title twice and leave the scraper to
+  pick.
+#}
+
+{% block extrahead %}
+  {{ super() }}
+
+  {% block social_meta %}
+    {#- `page` is None while the theme renders the 404, so every access here is
+        guarded. Without that the build dies with "'None' has no attribute
+        'meta'" and mkdocs does not say which template. -#}
+    {%- set page_title = (page.title if page else None) | default(config.site_name, true) -%}
+    {%- set page_description = (page.meta.description if page and page.meta else None)
+        | default(config.site_description, true) -%}
+    {%- set page_url = (page.canonical_url if page else config.site_url) -%}
+    <meta property="og:type" content="article">
+    <meta property="og:site_name" content="{{ config.site_name }}">
+    <meta property="og:title" content="{{ page_title }}">
+    <meta property="og:description" content="{{ page_description }}">
+    <meta property="og:url" content="{{ page_url }}">
+    <meta property="og:image" content="{{ config.site_url }}assets/og.png">
+    {# summary_large_image, not summary: the card is 1280×640 and a small
+       thumbnail wastes it. #}
+    <meta name="twitter:card" content="summary_large_image">
+    <meta name="twitter:title" content="{{ page_title }}">
+    <meta name="twitter:description" content="{{ page_description }}">
+    <meta name="twitter:image" content="{{ config.site_url }}assets/og.png">
+  {% endblock %}
+{% endblock %}