Documentation
lazarus / 21-General
----------------------------------------------------------------------
LemonParty · 2025-06-06 17:27
I want to create a documentation to my library. I suppose use html
files for this. Is there ready templates where is such things like
code highlighting and other beautifiers?
----------------------------------------------------------------------
dsiders · 2025-06-06 17:58
Quote from: LemonParty on June 06, 2025, 07:27:11 pmI want to create a
documentation to my library. I suppose use html files for this. Is
there ready templates where is such things like code highlighting and
other beautifiers?
There are a couple of tools available that can help with
documentation. FPC comes with FPDoc - the tool used to generate RTL,
FCL, LCL, and LazUtils. There is a 3rd party offering called PasDoc.
Both can be used to generated several output formats and include code
formatting and link generation tools.
HTH
----------------------------------------------------------------------
paule32 · 2025-06-06 18:11
I prefer HelpNDoc.com
- it is free for personal use
- you can codeing with a Script Pascal Engine your Templates
----------------------------------------------------------------------
LemonParty · 2025-06-07 13:35
Thank you for recomendations.
----------------------------------------------------------------------
LemonParty · 2025-06-08 12:58
FPDoc seems convinient instrument. How in FPDoc generate output HTML
files?
----------------------------------------------------------------------
marcov · 2025-06-08 13:05
Look on the FPC site documentation page, there you can download a
fpdoc manual
----------------------------------------------------------------------
LemonParty · 2025-06-08 13:46
Do you mean this https://www.freepascal.org/docs-html/fpdoc/fpdoc.html
manual?
----------------------------------------------------------------------
LemonParty · 2025-06-08 19:39
Accordingly to this page https://www.freepascal.org/docs-
html/fpdoc/fpdocse6.html#x11-100003.1 package name is required. But
can I generate documentation to units that are not part of a package?
----------------------------------------------------------------------
paule32 · 2025-06-09 14:10
If you like it old-school, you can doit by your own.
The following Python3 Script extracts XML Comments and write the XML
Data in Files:
Code: Text [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i #
----------------------------------------------------------------#
Copyright(c) 2025 @paule32# all rights reserved.## This file converts
xml data between the Pascal commands into a# xml format that can be
used to create documentation of Pascal# Souce Code.#
----------------------------------------------------------------import
osimport re from xml.etree import ElementTree as ETfrom xml.dom
import minidom # Konfigurationquellverzeichnis = "./" # <-- Pfad
anpassenunterverzeichnisse_durchsuchen = True # Alle .pas-Dateien
findendef finde_pascal_dateien(basisverzeichnis): for wurzel, _,
dateien in os.walk(basisverzeichnis): for datei in dateien:
if datei.lower().endswith(".pas"): yield
os.path.join(wurzel, datei) if not
unterverzeichnisse_durchsuchen: break # XML aus Kommentaren
extrahieren (alle Kommentararten)def extrahiere_xml_aus_code(code:
str): xml_blöcke = [] # 1. Einzelzeilige // Kommentare mit XML
matches = re.findall(r'//\s*<.*?>[\s\S]*?//\s*', code) for
block in matches: lines = block.splitlines() cleaned =
'\n'.join(line.lstrip('/ ').strip() for line in lines)
xml_blöcke.append(cleaned) # 2. Blockkommentare mit { ... }
matches = re.findall(r'\{\s*<.*?>[\s\S]*?\s*\s*\}', code) for
block in matches: cleaned = block.strip('{}').strip()
xml_blöcke.append(cleaned) # 3. Blockkommentare mit (* ... *)
matches = re.findall(r'\(\*\s*<.*?>[\s\S]*?\s*\s*\*\)', code)
for block in matches: cleaned =
block.strip('(*').strip('*)').strip()
xml_blöcke.append(cleaned) return xml_blöcke # XML-Datei
speicherndef speichere_xml(blöcke, zieldatei): if not blöcke:
return xml_inhalt = "\n" + "\n".join(blöcke) + "\n"
try: ET.fromstring(xml_inhalt) # Validierung
os.makedirs(os.path.dirname(zieldatei), exist_ok=True) with
open(zieldatei, "w", encoding="utf-8") as f:
f.write(xml_inhalt) print(f"Gespeichert: {zieldatei}")
except ET.ParseError as e: print(f"Fehler in XML in
{zieldatei}: {e}") # Hauptschleifedef hauptprogramm(): for
dateipfad in finde_pascal_dateien(quellverzeichnis): with
open(dateipfad, "r", encoding="utf-8") as f: code =
f.read() xml_blöcke = extrahiere_xml_aus_code(code) if
not xml_blöcke: continue basisverzeichnis =
os.path.dirname(dateipfad) dateiname =
os.path.splitext(os.path.basename(dateipfad))[0] + ".xml"
zielverzeichnis = os.path.join(basisverzeichnis, "xml")
zieldatei = os.path.join(zielverzeichnis, dateiname)
speichere_xml(xml_blöcke, zieldatei) def
zusammenfassen_aller_xml(basisverzeichnis, ausgabedatei):
zusammengeführt = [''] for wurzel, _, dateien in
os.walk(basisverzeichnis): if os.path.basename(wurzel) !=
"xml": continue # Nur die "xml"-Ordner beachten for
datei in dateien: if not datei.endswith(".xml"):
continue pfad = os.path.join(wurzel, datei)
try: with open(pfad, "r", encoding="utf-8") as f:
inhalt = f.read() # Inhalt ohne äußere
Hülle extrahieren match =
re.search(r"([\s\S]*)", inhalt) if match:
inhalt_ohne_root = match.group(1).strip()
else: inhalt_ohne_root = inhalt.strip()
relativname = os.path.relpath(pfad,
basisverzeichnis).replace('\\', '/')
zusammengeführt.append(f' ')
zusammengeführt.append(inhalt_ohne_root)
zusammengeführt.append(' ') except Exception as e:
print(f"Fehler beim Lesen von {pfad}: {e}")
zusammengeführt.append('') try: with
open(ausgabedatei, "w", encoding="utf-8") as f:
f.write('\n'.join(zusammengeführt)) print(f"Zusammengefasst in:
{ausgabedatei}") except Exception as e: print(f"Fehler beim
Schreiben der Zusammenfassung: {e}") def pretty_print_xml(eingabepfad,
ausgabepfad=None): try: with open(eingabepfad, "r",
encoding="utf-8") as f: raw_xml = f.read() dom =
minidom.parseString(raw_xml) schöner_xml =
dom.toprettyxml(indent=" ") if ausgabepfad is None:
ausgabepfad = eingabepfad # Überschreibt die Datei with
open(ausgabepfad, "w", encoding="utf-8") as f:
f.write(schöner_xml) print(f"Pretty Print abgeschlossen:
{ausgabepfad}") except Exception as e: print(f"Fehler beim
Pretty Print: {e}") if __name__ == "__main__": hauptprogramm()
# Schritt 1: Zusammenführen zielpfad =
os.path.join(quellverzeichnis, "all_data.xml")
zusammenfassen_aller_xml(quellverzeichnis, zielpfad) # Schritt 2:
Schön formatieren pretty_print_xml(zielpfad)
This File can be used as Template:
Code: Pascal [Select][+][-]window.onload = function(){var x1 =
document.getElementById("main_content_section"); if (x1) { var x =
document.getElementsByClassName("geshi");for (var i = 0; i // --------
----------------------------------------------------------------------
---------// Copyright(c) 2025 @paule32// -----------------------------
----------------------------------------------------------{$mode
delphi}unit Dialogs; interface uses global, Windows; {$ifdef
DLLEXPORT}// // param A// param
B// hallo// procedure ShowMessage(msg: PChar);
stdcall; export;{$endif DLLEXPORT} {$ifdef DLLIMPORT}procedure
ShowMessage(msg: PChar); stdcall; external RTLDLL;{$endif
DLLIMPORT} implementation {$ifdef DLLEXPORT}procedure ShowMessage(msg:
PChar); stdcall; export;begin MessageBoxA(0, msg, PChar(' '),
0);end;{$endif DLLEXPORT} {$ifdef DLLEXPORT}exports ShowMessage name
'ShowMessage' ;{$endif DLLEXPORT} end.
This will create then: all_data.xml and ./xml/Template.xml
happy gurking ...
----------------------------------------------------------------------
LemonParty · 2025-06-20 14:16
I am trying to generate documentation using fpdoc. I run this command:
Quotefpdoc.exe --package=fasta --descr=uFastaStrAnsi.pas
--format=htmland getting the following error:
QuoteException: Class - EXMLReadError
In 'file:uFastaStrAnsi.pas' (line 1 pos 1): Illegal at document
levelWhat the problem?
----------------------------------------------------------------------
dsiders · 2025-06-20 15:35
Quote from: LemonParty on June 20, 2025, 04:16:26 pmI am trying to
generate documentation using fpdoc. I run this command:
Quotefpdoc.exe --package=fasta --descr=uFastaStrAnsi.pas
--format=htmland getting the following error:
QuoteException: Class - EXMLReadError
In 'file:uFastaStrAnsi.pas' (line 1 pos 1): Illegal at document
levelWhat the problem?
--descr is the file with XML content for the documentation... not the
source code. That would be --input.
----------------------------------------------------------------------
LemonParty · 2025-06-20 17:08
QuoteThat would be --inputYes, that work. Documentation generates, but
I can't see the text that I added in FPDoc editor.
----------------------------------------------------------------------
dsiders · 2025-06-20 18:45
Quote from: LemonParty on June 20, 2025, 07:08:05 pmQuoteThat would be
--inputYes, that work. Documentation generates, but I can't see the
text that I added in FPDoc editor.
Do you mean "Not integrated into the IDE"? That's a whole other can of
wormas... and I recommend you check the Wiki.
----------------------------------------------------------------------
LemonParty · 2025-06-20 19:53
Quote from: dsiders on June 20, 2025, 08:45:12 pmQuote from:
LemonParty on June 20, 2025, 07:08:05 pmQuoteThat would be --inputYes,
that work. Documentation generates, but I can't see the text that I
added in FPDoc editor.
Do you mean "Not integrated into the IDE"? That's a whole other can of
wormas... and I recommend you check the Wiki.
No, it is integrated and I am able to edit description of a function.
But when I generate documentation using fpdoc.exe I can't see this
description in html files.
----------------------------------------------------------------------
LemonParty · 2025-06-20 20:03
I figured it out. I missed --descr option.