Codedocumentatie is een proces waarbij een programmeur code documenteert. Het is een bekende term onder ingenieurs. Als ze dit niet doen, leidt dit tot slechte leesbaarheid van de code en moeilijk onderhoud voor andere teamleden.
Code-documentatie is anders dan projectdocumentatie, omdat het zich vooral richt op hoe het systeem werkt, maar deze twee processen hebben iets gemeen – vereisten voor het gebruik van een professioneel hulpmiddel. In dit artikel geef ik een overzicht van enkele populaire hulpmiddelen voor het maken van codedocumentatie.
LaTex
LaTeX is een documentvoorbereidingssysteem voor hoogkwalitatief zetwerk. Het wordt meestal gebruikt voor middelgrote tot grote technische of wetenschappelijke documenten, maar het kan worden gebruikt voor bijna elke vorm van publicatie.
LaTeX is geen tekstverwerker! In plaats daarvan moedigt LaTeX auteurs aan zich niet te veel zorgen te maken over het uiterlijk van hun documenten, maar zich te concentreren op de juiste inhoud.
LaTeX is een zetsysteem van hoge kwaliteit; het bevat functies die zijn ontworpen voor de productie van technische en wetenschappelijke documentatie. LaTeX is de de facto standaard voor de communicatie en publicatie van wetenschappelijke documenten. LaTeX is beschikbaar als vrije software.
U hoeft niet te betalen voor het gebruik van LaTeX, d.w.z.,
Pandoc
Pandoc begrijpt een aantal handige markdown syntaxisuitbreidingen, waaronder documentmetadata (titel, auteur, datum); voetnoten; tabellen; definitielijsten; superscript en subscript; doorhalen; verbeterde geordende lijsten (startnummer en nummeringsstijl zijn belangrijk); lijsten met lopende voorbeelden; afgebakende codeblokken met syntax highlighting; slimme aanhalingstekens, streepjes, en ellipsen; markdown binnen HTML-blokken; en inline LaTeX. Als strikte markdown-compatibiliteit gewenst is, kunnen al deze extensies worden uitgeschakeld.
Er zijn veel manieren om Pandoc aan uw behoeften aan te passen, waaronder een sjabloonsysteem en een krachtig systeem voor het schrijven van filters.
Pandoc bevat een Haskell-bibliotheek en een standalone opdrachtregelprogramma. De bibliotheek bevat aparte modules voor elk invoer- en uitvoerformaat, dus voor het toevoegen van een nieuw invoer- of uitvoerformaat hoeft alleen maar een nieuwe module te worden toegevoegd.
Pandoc is vrije software, vrijgegeven onder de GPL.
Markdown
Markdown is een tekst-naar-HTML conversieprogramma voor webschrijvers. Met Markdown kun je schrijven in een gemakkelijk te lezen, gemakkelijk te schrijven platte tekst-indeling, en die vervolgens converteren naar structureel geldige XHTML (of HTML).
Het belangrijkste ontwerpdoel voor de opmaaksyntaxis van Markdown is om het zo leesbaar mogelijk te maken. Het idee is dat een Markdown-geformatteerd document publiceerbaar moet zijn zoals het is, als platte tekst, zonder dat het eruit ziet alsof het is gemarkeerd met tags of opmaakinstructies. Hoewel de Markdown-syntaxis is beïnvloed door verschillende bestaande tekst-naar-HTML filters, is de grootste inspiratiebron voor Markdowns syntaxis het formaat van platte tekst e-mail.
LiveEdu
LiveEdu stelt je in staat om je codedocumentatie uit te zenden en “Video codedocumentatie” te maken.”
Education Ecosystem is een gedecentraliseerd leerecosysteem dat professionals en universiteitsstudenten leert hoe ze echte producten moeten bouwen. Je kunt ons product beschrijven als een hybride van Pluralsight en Twitch. We bouwen ’s werelds grootste leerecosysteem voor toekomstige technologische onderwerpen zoals kunstmatige intelligentie, cybersecurity, game-ontwikkeling, data science, cryptocurrencies, en programmeren. Education Ecosystem is gebaseerd op video’s en elk project bevat video’s, een gestructureerde project outline, project repo, en downloadbare bronnen. Gebruikers kunnen projectbronnen klonen van de Education Ecosystem Git en de toepassingen op hun lokale machine uitvoeren.
Sphinx
Sphinx is een tool waarmee je eenvoudig intelligente en mooie documentatie kunt maken, geschreven door Georg Brandl en gelicenseerd onder de BSD-licentie.
Het is oorspronkelijk gemaakt voor de Python-documentatie, en het heeft uitstekende faciliteiten voor de documentatie van softwareprojecten in een reeks van talen. Hier zijn enkele kenmerken:
- Uitvoerformaten: HTML (inclusief Windows HTML Help), LaTeX (voor afdrukbare PDF-versies), ePub, Texinfo, handleidingen, platte tekst.
- Uitgebreide kruisverwijzingen: semantische markup en automatische links voor functies, klassen, citaten, termen uit de woordenlijst, en soortgelijke stukken informatie.
- Hiërarchische structuur: eenvoudige definitie van een documentboom, met automatische links naar broers en zussen, ouders, en kinderen.