Transclusion de symboles
Écrivez un wiki-link vers un nom de fonction et le corps de la fonction s'affiche en place avec coloration syntaxique, extrait directement de vos fichiers sources. L'extraction par AST fonctionne pour 40+ langages : Python, Swift, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, Kotlin et plus. Modifiez la source, le document se met à jour.
# Intégrer une fonction par son nom
![[auth.py#validate_token]]Ohai extrait la fonction validate_token depuis auth.py et l'affiche en ligne avec coloration syntaxique. Quand la fonction change, votre documentation se met à jour automatiquement.
Pourquoi c'est important
La documentation traditionnelle pourrit. Vous copiez-collez du code dans du markdown, le code évolue, et soudain votre documentation vous ment. La transclusion de symboles résout ce problème en traitant vos fichiers sources comme unique source de vérité.
Contrairement aux références par numéro de ligne qui cassent à chaque refactorisation, la transclusion de symboles utilise l'analyse AST pour trouver le code par son vrai nom : fonctions, classes, structures, constantes. Renommez un fichier, réorganisez votre code, ajoutez de nouvelles méthodes : tant que le nom du symbole existe, votre documentation reste exacte.
Cas d'usage
Documentation API
Référencez vos vraies signatures de fonctions, pas des approximations tapées à la main qui se désynchronisent.
Registre de décisions d'architecture
Intégrez le code dont vous discutez dans vos ADR. Les exemples restent à jour au fil de l'évolution du code.
Guides d'intégration
Montrez aux nouveaux développeurs comment fonctionne l'authentification avec du code en direct dont ils peuvent se fier qu'il correspond au dépôt.
Revues de code
Extrayez des fonctions spécifiques dans un résumé markdown pour discussion et revue asynchrones.
Tutoriels
Parcourez de vraies implémentations. Les lecteurs peuvent être sûrs que les exemples de code sont toujours à jour.
Playbooks opérationnels
Intégrez exactement la configuration ou le script dont l'équipe ops a besoin lors des incidents.
Langages pris en charge
Analyse AST Tree-sitter pour Python, Swift, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, Kotlin, PHP, Scala, Haskell, OCaml, Lua, Elixir, Bash et plus — plus des extracteurs de chemins de formats de données pour les clés JSON, chemins YAML, tables TOML, chemins plist, XML, CSS, SQL et texte brut. 40+ formats au total.
Prêt à essayer une documentation qui ne vieillit jamais ?
Télécharger pour Mac