Transkluzja symboli
Osadzaj aktywny kod w dokumentacji po nazwie, a nie numerze linii. Edytuj źródło, a dokumentacja zaktualizuje się automatycznie.
# Osadź funkcję po nazwie
![[auth.py#validate_token]]Ohai wyodrębnia funkcję validate_token z auth.py i renderuje ją inline z podświetlaniem składni. Gdy funkcja się zmieni, dokumentacja zaktualizuje się automatycznie.
Dlaczego to ma znaczenie
Tradycyjna dokumentacja się starzeje. Kopiujesz kod do markdown, kod ewoluuje i nagle dokumentacja cię okłamuje. Transkluzja symboli rozwiązuje ten problem, traktując pliki źródłowe jako jedyne źródło prawdy.
W przeciwieństwie do referencji numerów linii, które psują się przy każdym refaktoryzowaniu, transkluzja symboli używa parsowania AST do znajdowania kodu po rzeczywistej nazwie — funkcji, klas, struktur, stałych. Zmień nazwę pliku, zreorganizuj kod, dodaj nowe metody — dopóki nazwa symbolu istnieje, dokumentacja pozostaje dokładna.
Przypadki użycia
Dokumentacja API
Odwołuj się do rzeczywistych sygnatur funkcji, nie ręcznie pisanych przybliżeń, które się rozjeżdżają.
Zapisy decyzji architektonicznych
Osadzaj kod, który omawiasz w ADR. Przykłady pozostają aktualne wraz z ewolucją kodu.
Przewodniki wdrożeniowe
Pokaż nowym programistom, jak działa uwierzytelnianie z aktywnym kodem, któremu mogą zaufać, że pasuje do repozytorium.
Przeglądy kodu
Wyciągnij konkretne funkcje do podsumowania markdown dla asynchronicznej recenzji i dyskusji.
Samouczki
Przeprowadź przez rzeczywiste implementacje. Czytelnicy mogą ufać, że przykłady kodu są zawsze aktualne.
Runbooki
Osadź dokładną konfigurację lub skrypt, do którego ops musi się odwołać podczas incydentów.
Obsługiwane języki
Ponad 30 języków przez parsowanie AST Tree-sitter. Nawet klucze JSON, ścieżki YAML i tabele TOML.
Gotowy spróbować dokumentacji, która nigdy się nie starzeje?
Pobierz na Mac