Edycja dokumentacji

Treść znajduje się w plikach docs/*.md i docs/packages/*.md. Edytuj źródła, a następnie uruchom skrypt z katalogu projektu.

Codzienna aktualizacja na bose

./publish.sh

Skrypt buduje stronę, sprawdza lokalne odnośniki i publikuje nową wersję. Nie wymaga sudo po jednorazowym przygotowaniu usługi. Błąd budowania pozostawia poprzednią wersję dostępną. Serwer nie wykonuje poleceń z dokumentacji.

Podgląd i budowanie bez publikacji

./build.sh
./preview.sh

Podgląd: http://127.0.0.1:8000. Zakończ go przez Ctrl-C. Skrypt podglądu służy do pracy nad dokumentacją; trwały serwis korzysta z nginx.

Jeśli edytujesz na bose i przeglądasz na swoim komputerze:

ssh -N -L 8000:127.0.0.1:8000 bose

Otwórz potem http://127.0.0.1:8000 na swoim komputerze.

Nowa strona

Dodaj plik, np. docs/packages/dalton.md. Dopisz go do nav w mkdocs.yml, jeśli ma pojawić się w menu, i dodaj odnośnik z katalogu pakietów. Nazwy plików najlepiej zapisywać bez spacji i polskich znaków.

Używaj nagłówków # i ##, list, tabel oraz bloków poleceń:

```bash
Orca -c 4 -m 8 water.inp
```

Odnośniki między stronami zapisuj względem pliku źródłowego, np. [Kolejki](queues.md). Pliki do pobrania umieszczaj w docs/examples/. Wszystko z docs/ jest przeznaczone do opublikowania — nie umieszczaj tu haseł, kluczy, licencji ani prywatnych wyników.

Wycofanie aktualizacji

ls /srv/bose-docs/releases
./rollback.sh NAZWA_WERSJI

Zastąp NAZWA_WERSJI nazwą zachowanego katalogu. Poprzednie wersje nie są automatycznie kasowane. Lokalne kompilacje pozostają w builds/; można usuwać starsze katalogi, zachowując ten wskazywany przez site.

Pierwsze uruchomienie

./bootstrap.sh
./build.sh
./install-service.sh --plan
sudo ./install-service.sh --apply "$USER"

bootstrap.sh tworzy prywatne środowisko .venv i pobiera MkDocs. Wymaga Python 3.11+ z venv, dostępu do indeksu pakietów oraz certyfikatów TLS. Na Debianie administrator zapewnia python3-venv i nginx. Instalacja pakietu nginx może uruchomić jego domyślną usługę; administrator powinien sprawdzić jej konfigurację i dostęp sieciowy przed instalacją.

Własna usługa bose-docs udostępnia dokumentację na https://bose.ch.pwr.wroc.pl/ i http://156.17.2.232/; port 127.0.0.1:8080 pozostaje dostępny lokalnie do sprawdzania stanu. Dostęp z komputera użytkownika:

ssh -N -L 8080:127.0.0.1:8080 bose

Otwórz http://127.0.0.1:8080. Dostęp publiczny nie wymaga tunelu. HTTPS korzysta z automatycznie odnawianego certyfikatu Let’s Encrypt. Wejścia HTTP, także po IP, przekierowują na nazwę bose.ch.pwr.wroc.pl z HTTPS.