Documentation

[LemonParty]

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]

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?

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]

I prefer HelpNDoc.com
- it is free for personal use
- you can codeing with a Script Pascal Engine your Templates

[LemonParty]

Thank you for recomendations.

[LemonParty]

FPDoc seems convinient instrument. How in FPDoc generate output HTML files?

[marcov]

Look on the FPC site documentation page, there you can download a fpdoc manual

[LemonParty]

Do you mean this https://www.freepascal.org/docs-html/fpdoc/fpdoc.html manual?

[LemonParty]

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]

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][+][-]

1. # ----------------------------------------------------------------
2. # Copyright(c) 2025 @paule32
3. # all rights reserved.
4. #
5. # This file converts xml data between the Pascal commands into a
6. # xml format that can be used to create documentation of Pascal
7. # Souce Code.
8. # ----------------------------------------------------------------
9. import os
10. import re
11.  
12. from xml.etree import ElementTree as ET
13. from xml.dom   import minidom
14.  
15. # Konfiguration
16. quellverzeichnis = "./"  # <-- Pfad anpassen
17. unterverzeichnisse_durchsuchen = True
18.  
19. # Alle .pas-Dateien finden
20. def finde_pascal_dateien(basisverzeichnis):
21.     for wurzel, _, dateien in os.walk(basisverzeichnis):
22.         for datei in dateien:
23.             if datei.lower().endswith(".pas"):
24.                 yield os.path.join(wurzel, datei)
25.         if not unterverzeichnisse_durchsuchen:
26.             break
27.  
28. # XML aus Kommentaren extrahieren (alle Kommentararten)
29. def extrahiere_xml_aus_code(code: str):
30.     xml_blöcke = []
31.  
32.     # 1. Einzelzeilige // Kommentare mit XML
33.     matches = re.findall(r'//\s*<.*?>[\s\S]*?//\s*</.*?>', code)
34.     for block in matches:
35.         lines = block.splitlines()
36.         cleaned = '\n'.join(line.lstrip('/ ').strip() for line in lines)
37.         xml_blöcke.append(cleaned)
38.  
39.     # 2. Blockkommentare mit { ... }
40.     matches = re.findall(r'\{\s*<.*?>[\s\S]*?\s*</.*?>\s*\}', code)
41.     for block in matches:
42.         cleaned = block.strip('{}').strip()
43.         xml_blöcke.append(cleaned)
44.  
45.     # 3. Blockkommentare mit (* ... *)
46.     matches = re.findall(r'\(\*\s*<.*?>[\s\S]*?\s*</.*?>\s*\*\)', code)
47.     for block in matches:
48.         cleaned = block.strip('(*').strip('*)').strip()
49.         xml_blöcke.append(cleaned)
50.  
51.     return xml_blöcke
52.  
53. # XML-Datei speichern
54. def speichere_xml(blöcke, zieldatei):
55.     if not blöcke:
56.         return
57.     xml_inhalt = "<root>\n" + "\n".join(blöcke) + "\n</root>"
58.     try:
59.         ET.fromstring(xml_inhalt)  # Validierung
60.         os.makedirs(os.path.dirname(zieldatei), exist_ok=True)
61.         with open(zieldatei, "w", encoding="utf-8") as f:
62.             f.write(xml_inhalt)
63.         print(f"Gespeichert: {zieldatei}")
64.     except ET.ParseError as e:
65.         print(f"Fehler in XML in {zieldatei}: {e}")
66.  
67. # Hauptschleife
68. def hauptprogramm():
69.     for dateipfad in finde_pascal_dateien(quellverzeichnis):
70.         with open(dateipfad, "r", encoding="utf-8") as f:
71.             code = f.read()
72.  
73.         xml_blöcke = extrahiere_xml_aus_code(code)
74.         if not xml_blöcke:
75.             continue
76.  
77.         basisverzeichnis = os.path.dirname(dateipfad)
78.         dateiname = os.path.splitext(os.path.basename(dateipfad))[0] + ".xml"
79.         zielverzeichnis = os.path.join(basisverzeichnis, "xml")
80.         zieldatei = os.path.join(zielverzeichnis, dateiname)
81.  
82.         speichere_xml(xml_blöcke, zieldatei)
83.  
84. def zusammenfassen_aller_xml(basisverzeichnis, ausgabedatei):
85.     zusammengeführt = ['<all_files>']
86.     for wurzel, _, dateien in os.walk(basisverzeichnis):
87.         if os.path.basename(wurzel) != "xml":
88.             continue  # Nur die "xml"-Ordner beachten
89.         for datei in dateien:
90.             if not datei.endswith(".xml"):
91.                 continue
92.             pfad = os.path.join(wurzel, datei)
93.             try:
94.                 with open(pfad, "r", encoding="utf-8") as f:
95.                     inhalt = f.read()
96.                 # Inhalt ohne äußere <root> Hülle extrahieren
97.                 match = re.search(r"<root>([\s\S]*)</root>", inhalt)
98.                 if match:
99.                     inhalt_ohne_root = match.group(1).strip()
100.                 else:
101.                     inhalt_ohne_root = inhalt.strip()
102.  
103.                 relativname = os.path.relpath(pfad, basisverzeichnis).replace('\\', '/')
104.                 zusammengeführt.append(f'  <file name="{relativname}">')
105.                 zusammengeführt.append(inhalt_ohne_root)
106.                 zusammengeführt.append('  </file>')
107.             except Exception as e:
108.                 print(f"Fehler beim Lesen von {pfad}: {e}")
109.  
110.     zusammengeführt.append('</all_files>')
111.     try:
112.         with open(ausgabedatei, "w", encoding="utf-8") as f:
113.             f.write('\n'.join(zusammengeführt))
114.         print(f"Zusammengefasst in: {ausgabedatei}")
115.     except Exception as e:
116.         print(f"Fehler beim Schreiben der Zusammenfassung: {e}")
117.  
118. def pretty_print_xml(eingabepfad, ausgabepfad=None):
119.     try:
120.         with open(eingabepfad, "r", encoding="utf-8") as f:
121.             raw_xml = f.read()
122.         dom = minidom.parseString(raw_xml)
123.         schöner_xml = dom.toprettyxml(indent="  ")
124.  
125.         if ausgabepfad is None:
126.             ausgabepfad = eingabepfad  # Überschreibt die Datei
127.  
128.         with open(ausgabepfad, "w", encoding="utf-8") as f:
129.             f.write(schöner_xml)
130.         print(f"Pretty Print abgeschlossen: {ausgabepfad}")
131.     except Exception as e:
132.         print(f"Fehler beim Pretty Print: {e}")
133.  
134. if __name__ == "__main__":
135.     hauptprogramm()
136.    
137.     # Schritt 1: Zusammenführen
138.     zielpfad = os.path.join(quellverzeichnis, "all_data.xml")
139.     zusammenfassen_aller_xml(quellverzeichnis, zielpfad)
140.  
141.     # Schritt 2: Schön formatieren
142.     pretty_print_xml(zielpfad)
143.  

This File can be used as Template:

Code: Pascal  [Select][+][-]

1. // ---------------------------------------------------------------------------------------
2. // Copyright(c) 2025 @paule32
3. // ---------------------------------------------------------------------------------------
4. {$mode delphi}
5. unit Dialogs;
6.  
7. interface
8.  
9. uses global, Windows;
10.  
11. {$ifdef DLLEXPORT}
12. // <info>
13. //  <param>param A</param>
14. //  <param>param B</param>
15. //   hallo
16. // </info>
17. procedure ShowMessage(msg: PChar); stdcall; export;
18. {$endif DLLEXPORT}
19.  
20. {$ifdef DLLIMPORT}
21. procedure ShowMessage(msg: PChar); stdcall; external RTLDLL;
22. {$endif DLLIMPORT}
23.  
24. implementation
25.  
26. {$ifdef DLLEXPORT}
27. procedure ShowMessage(msg: PChar); stdcall; export;
28. begin
29.   MessageBoxA(0, msg, PChar(' '), 0);
30. end;
31. {$endif DLLEXPORT}
32.  
33. {$ifdef DLLEXPORT}
34. exports
35.   ShowMessage name 'ShowMessage'
36.   ;
37. {$endif DLLEXPORT}
38.  
39. end.

This will create then:  all_data.xml and ./xml/Template.xml

happy gurking ...

[LemonParty]

I am trying to generate documentation using fpdoc. I run this command:

fpdoc.exe --package=fasta --descr=uFastaStrAnsi.pas --format=html

and getting the following error:

Exception: Class - EXMLReadError
In 'file:uFastaStrAnsi.pas' (line 1 pos 1): Illegal at document level

What the problem?

[dsiders]

I am trying to generate documentation using fpdoc. I run this command:

fpdoc.exe --package=fasta --descr=uFastaStrAnsi.pas --format=html

and getting the following error:

Exception: Class - EXMLReadError
In 'file:uFastaStrAnsi.pas' (line 1 pos 1): Illegal at document level

What the problem?

--descr is the file with XML content for the documentation... not the source code. That would be --input.

[LemonParty]

That would be --input

Yes, that work. Documentation generates, but I can't see the text that I added in FPDoc editor.

[dsiders]

That would be --input

Yes, 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]

That would be --input

Yes, 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]

I figured it out. I missed --descr option.