Zrzuty ekranu do dokumentacji i bazy wiedzy¶
Zrzuty z oznaczeniami (ramki, strzałki, podpisy) do instrukcji w docs/
i do artykułów bazy wiedzy Freshdesk robi skrypt
bin/docs-screenshots.py. Zrzutów nie robimy ręcznie — skrypt odtwarza
je jednym poleceniem, więc po zmianie interfejsu wystarczy go uruchomić
ponownie.
Gdzie co leży¶
| Co | Gdzie |
|---|---|
| Pliki PNG | docs/images/<sekcja>/<scenariusz>/NN-opis.png, np. docs/images/uzytkownik/moj-profil-autora/01-menu-konto.png |
| Scenariusze (co klikamy, co oznaczamy) | funkcje w bin/docs-screenshots.py, słownik SCENARIOS |
| Publiczny adres obrazka | https://iplweb.github.io/bpp/images/<sekcja>/<scenariusz>/NN-opis.png |
Obrazki są jedno źródło dla dokumentacji i bazy wiedzy: strona w
docs/ osadza je ścieżką względną, a artykuł we Freshdesku linkuje ten sam
plik z GitHub Pages (<img src="https://iplweb.github.io/bpp/images/…">).
Nie przenoś i nie zmieniaj nazw plików bez sprawdzenia Freshdesku
Artykuły bazy wiedzy linkują obrazki po pełnym adresie. Po zmianie ścieżki obrazek w artykule po cichu przestaje się wyświetlać. Nowa wersja zrzutu = nadpisanie pliku pod tą samą nazwą.
Reguły¶
Dane. Wyłącznie dane demo (create_demo_data), nigdy zrzut bazy
klienta — na obrazku nie może się znaleźć prawdziwe nazwisko, uczelnia ani
adres. Domyślnie motyw Wiedźmin (--motyw wiedzmin) z flagą
--bez-prefiksu — bez niej nazwy mają przedrostek „Demo —”, który na
zrzucie wygląda jak błąd.
Konto. Zrzuty z punktu widzenia użytkownika robimy na zwykłym
koncie demo yennefer (bez is_staff/is_superuser), powiązanym z
autorem. Konto admina pokazuje pozycje menu, których zwykły użytkownik nie
ma (np. „zaloguj jako inny użytkownik”). Zrzuty dla redaktora/administratora
— na koncie z odpowiednią grupą, nie na superuserze, chyba że opisujemy
funkcję wyłącznie dla superusera.
Przeglądarka. Okno 1280×800, device_scale_factor=2 (ostre na
ekranach HiDPI), język polski. Pełny Chromium (channel="chromium"), nie
„headless shell” — tylko on respektuje --lang=pl, inaczej natywne
kontrolki mówią „Choose File” zamiast „Wybierz plik”. Baner ciasteczek
zamykamy przed zrzutem.
Oznaczenia — jeden styl na wszystkich zrzutach:
- kolor
#e8173c; ramka 4 px z zaokrągleniem wokół elementu, - zakrzywiona strzałka 5 px z grotem, z cieniem,
- podpis pogrubiony, w białej ramce z cieniem — czytelny na każdym tle,
- kroki numerujemy w podpisach („1. konto”, „2. mój profil”), gdy kolejność ma znaczenie,
- oznaczenia są rysowane w stronie (nakładka SVG) i przypięte do selektorów CSS elementów — nie do współrzędnych. Po zmianie układu strony same trafiają we właściwe miejsce,
- podpis nie może zasłaniać tekstu ani innej ramki. Kierunek strzałki
(
arrow:left/right/above/below) i przesunięcie podpisu (dx/dy) dobieramy tak, żeby podpis stał w pustym miejscu.
Adresy. Na zrzutach nie może być localhost:PORT. Skrypt podstawia
lokalny BPP pod adres https://bpp.twoja-uczelnia.pl (PUBLIC_BPP,
funkcja proxy_public_bpp) wszędzie tam, gdzie adres serwera widać na
ekranie — np. w kodzie do wklejenia.
Strona „u klienta”. Gdy trzeba pokazać efekt na zewnętrznej stronie
(np. widget publikacji), używamy wymyślonej strony z motywu demo
(EXAMPLE_PAGE w skrypcie, adres https://katedra.example), nigdy strony
prawdziwej uczelni.
Element daleko na stronie. Gdy klikany element jest np. na samym dole
długiej strony, sam wycinek nie mówi, gdzie go szukać. Robimy wtedy jeden
obrazek z dwóch kadrów — góra strony (żeby było wiadomo, jaka to strona),
„rozdarcie” z podpisem (np. „przewiń na sam dół strony”), potem fragment
z oznaczonym elementem. Służy do tego funkcja stitch() w skrypcie.
Kadr. Tylko fragment, o którym mowa w tekście (clip=), chyba że zrzut
pokazuje cały formularz. Każdy zrzut obejrzyj po wygenerowaniu —
nakładające się podpisy i niedokończone animacje (rozwijane menu) widać
dopiero na obrazku.
Artykuły w bazie wiedzy (Freshdesk)¶
Artykuł we Freshdesku to skrót strony z docs/, nie jej kopia. Widżet
pomocy wyświetla go w małym okienku, więc:
- zostaje tylko: gdzie kliknąć, skąd skopiować, co się stanie,
- obrazki te same co w
docs/(adres z GitHub Pages), w krokach, których dotyczą, - bez uwag technicznych — parametrów, klas CSS, stylów, szczegółów
konfiguracji; te zostają w
docs/, - na końcu odnośnik „Szczegóły” do strony w dokumentacji.
Jak wygenerować¶
-
Postaw stack i bazę demo (szczegóły: Dane demo):
uv run run-site run --no-browser --no-celery # w tle; port z bannera source .run-site-env.sh export DJANGO_BPP_SKIP_DOTENV=1 DJANGO_BPP_DB_HOST=localhost \ DJANGO_BPP_DB_PORT=$PGPORT DJANGO_BPP_DB_NAME=bpp \ DJANGO_BPP_DB_USER=bpp DJANGO_BPP_DB_PASSWORD=password uv run python src/manage.py seed_default_dyscypliny uv run python src/manage.py create_demo_data --motyw wiedzmin --bez-prefiksu \ --wydzialow 4 --jednostek-na-wydzial 3 --autorow 120 \ --ile-ciaglych 600 --ile-zwartych 300 --zrodel 20 --wydawcow 8 \ --seed 42 --yes-i-am-sure --confirm-db bpp uv run python src/manage.py denorm_flush.run-site-env.sheksportuje tylkoDATABASE_URL/PG*, a ustawienia BPP czytająDJANGO_BPP_DB_*— stąd drugiexport. -
Załóż konto demo powiązane z autorem:
uv run python src/manage.py shell -c " from bpp.models import Autor, BppUser from password_policies.models import PasswordHistory a = Autor.objects.filter(imiona='Yennefer', nazwisko='Merigold').first() u, _ = BppUser.objects.get_or_create(username='yennefer', defaults=dict( email='yennefer@example.com', first_name='Yennefer', last_name='z Vengerbergu')) u.set_password('yennefer'); u.autor = a; u.save() PasswordHistory.objects.create(user=u, password=u.password) "Hasło = login (
yennefer) — to lokalna baza demo, a hasło o wyglądzie „prawdziwego” zatrzymuje PR na skanerze sekretów (GitGuardian). Wpis wPasswordHistoryjest potrzebny, inaczej polityka haseł przekierowuje świeże konto na zmianę hasła i zrzut pokazuje zły ekran.Dwa kolejne konta tak samo (hasło = login, wpis w
PasswordHistory):jaskier— bez powiązanego autora (zrzut „Brak powiązania z autorem”),filippa— w grupie „generowanie raportów” (menu raporty/ewaluacja, raporty slotów). -
Sloty. Generator danych demo nie wpisuje dyscyplin przy autorach prac, więc raporty slotów byłyby puste. Uzupełnia to skrypt:
-
Gotową bazę warto zrzucić (
pg_dump -Fc) i następnym razem startować z niej:uv run run-site run --from-dump <plik>— kroki 1–3 odpadają. -
Raz na maszynie:
uv run playwright install chromium. Scenariusze, które przechodzą na stronę dokumentacji (np.widget-publikacji— generator kodu mieszka na GitHub Pages), wymagają zbudowanej dokumentacji:mkdocs build(katalogsite/). Skrypt podstawia ją pod adreshttps://iplweb.github.io/bpp/, bo z prawdziwej strony HTTPS przeglądarka nie pozwoliłaby wczytać widgetu z lokalnego BPP pohttp. -
Wygeneruj i obejrzyj:
Nowy scenariusz¶
Dopisz funkcję def nazwa(page, base, out) w bin/docs-screenshots.py
(wzór: moj_profil_autora) i wpis w SCENARIOS. W funkcji: przejdź na
stronę, poczekaj na networkidle (i na koniec animacji, jeśli coś się
rozwija), wywołaj mark(page, [...]), zrób page.screenshot(...).
Następnie osadź obrazki na stronie w docs/ i — jeśli jest artykuł
w bazie wiedzy — podlinkuj je tam adresem z GitHub Pages po opublikowaniu
dokumentacji (budowa po pushu do dev).