feat(generation): add markdown output of documentation

Author: SuperFola

.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Checkout std
         uses: actions/checkout@v2

README.md

@@ -28,10 +28,10 @@ python3 -m arkdoc --help
 
 - `@brief <description>`: a single brief declaration is expected
 - `@param <name> <description>`: multiple `@param` declaration can be written
-- `@details <description>`: a single detailled declaration is expected
+- `@details <description>`: a single detailed declaration is expected
 - `=begin` / code block / `=end`: a single code block (it can contain multiple lines) is expected
 - `@author <url>,<url>,...`: the url to the profiles of the authors must be separated by commas, spaces can be added
-- any line not starting with a `@<keyword>` will be ignored, unless it is enclosed in a `=begin`/`=end` bloc
+- any line not starting with a `@<keyword>` will be ignored, unless it is enclosed in a `=begin`/`=end` block
 
 ## Example
 
@@ -44,18 +44,15 @@ python3 -m arkdoc --help
 # (import "List.ark")
 # (let collection [1 2 5 12])
 # (list:forEach collection (fun (element) {
-#     (print element)
-# }))
+#     (print element) }))
 # =end
 # @author https://github.com/SuperFola
 (let list:forEach (fun (_L _func) {
     (mut _index 0)
     (while (< _index (len _L)) {
         (mut _element (@ _L _index))
         (_func _element)
-        (set _index (+ 1 _index))
-    })
-}))
+        (set _index (+ 1 _index)) })}))
 ```
 
 ## The project architecture

arkdoc/__main__.py

@@ -9,7 +9,7 @@
 from . import logger
 from .logger_utils import LogLevel
 from .reader import parse_all_in
-from .generator import HTMLGenerator
+from .generator import HTMLGenerator, MDGenerator
 
 
 EXIT_SUCCESS = 0
@@ -58,7 +58,7 @@ def compute(args) -> bool:
                 prefix = os.path.splitext(os.path.basename(p.filename))[0].lower()
                 for doc in p.extract_documentation():
                     if doc.source == Source.ArkScript:
-                        kw, name, *args = doc.signature()
+                        kw, name, args = doc.signature()
                         if kw == "$" or kw == "macro":
                             # macro! (handling both $ and macro for retro compatibility for now (21/05/2025))
                             functions.append(name)
@@ -74,6 +74,9 @@ def compute(args) -> bool:
         if args.html:
             gen = HTMLGenerator(parsers, args.html, args.ark_version, args.root_dir)
             gen()
+        elif args.markdown:
+            gen = MDGenerator(parsers, args.markdown, args.ark_version, args.root_dir)
+            gen()
         else:
             logger.error("Missing generator!")
             return False
@@ -98,6 +101,7 @@ def main() -> int:
         help="Extract only the function names, print them on separate lines and exit",
     )
     cli.add_argument("--html", type=str, help="Output folder for the HTML docs")
+    cli.add_argument("--markdown", type=str, help="Output folder for the Markdown docs")
     cli.add_argument(
         "--root-dir", type=str, default="", help="The root dir for the links"
     )

arkdoc/generator/__init__.py

@@ -2,5 +2,7 @@
 
 from . import specification
 from .utils import documentation_to_specification
+from .formatter import Formatter
 from .base import Generator
 from .html import HTMLGenerator
+from .markdown import MDGenerator

arkdoc/generator/base.py

@@ -5,23 +5,25 @@
 from typing import List
 from pathlib import Path
 
-from . import specification as spec
+from . import specification as spec, Formatter
 from . import documentation_to_specification
 from .. import logger
 from ..parser import Parser
 
 
 class Generator:
     def __init__(
-        self,
-        parsers: List[Parser],
-        template_folder: Path,
-        pattern: str,
-        output: str,
-        ark_version: str,
-        root: str,
+            self,
+            parsers: List[Parser],
+            template_folder: Path,
+            formatter: Formatter,
+            pattern: str,
+            output: str,
+            ark_version: str,
+            root: str,
     ):
         self.template_folder = template_folder
+        self.formatter = formatter
         self.templates = {
             file.name: file.read_text("utf-8") for file in template_folder.glob(pattern)
         }
@@ -54,6 +56,51 @@ def _create_files_list(self, parsers: List[Parser]):
     def generate_index(self):
         raise NotImplementedError
 
+    def generate_sections(self, functions: List[spec.Function], with_hr: bool=False):
+        sections = ""
+
+        for func in functions:
+            authors = (
+                self.formatter.div(
+                    self.formatter.h4(self.formatter.plural("Author", len(func.desc.authors))),
+                    ", ".join(
+                        [self.formatter.a(f"@{a.split('/')[-1]}", a) for a in func.desc.authors]
+                    ),
+                )
+                if func.desc.authors
+                else ""
+            )
+            parameters = (
+                self.formatter.div(
+                    self.formatter.h4(self.formatter.plural("Parameter", len(func.desc.params))),
+                    self.formatter.ul(
+                        [
+                            f"{self.formatter.inline_code(p.name)}: {p.desc}"
+                            for p in func.desc.params
+                        ]
+                    ),
+                )
+                if func.desc.params
+                else ""
+            )
+            content = self.formatter.div(
+                self.formatter.div(self.formatter.inline_code(func.signature)),
+                self.formatter.div(func.desc.brief),
+                self.formatter.new_line(),
+                self.formatter.div(self.formatter.b("Note"), ": ", func.desc.details) if func.desc.details else "",
+                parameters,
+                authors,
+            )
+            if func.desc.code:
+                content += self.formatter.div(self.formatter.h4("Example"), self.formatter.code(func.desc.code))
+            sections += self.formatter.section(
+                func.name,
+                (self.formatter.hr() if with_hr else "") + content,
+                anchor=self.formatter.anchorize(func.name)
+            )
+
+        return sections
+
     def generate_one(self, path: str, functions: List[spec.Function]):
         raise NotImplementedError
 

arkdoc/generator/formatter.py

@@ -0,0 +1,51 @@
+from typing import List
+
+
+class Formatter:
+    def plural(self, name: str, qu: int) -> str:
+        return f"{name}{'s' if qu > 1 else ''}"
+
+    def anchorize(self, name: str) -> str:
+        return name.lower().replace(" ", "-")
+
+    def nav_item(self, name: str, anchor: str) -> str:
+        raise NotImplementedError
+
+    def a(self, name: str, path: str) -> str:
+        raise NotImplementedError
+
+    def b(self, content: str) -> str:
+        raise NotImplementedError
+
+    def inline_code(self, content: str) -> str:
+        raise NotImplementedError
+
+    def code(self, content: str) -> str:
+        raise NotImplementedError
+
+    def section(self, title: str, content: str, anchor: str = "") -> str:
+        raise NotImplementedError
+
+    def ul(self, content: List[str]) -> str:
+        raise NotImplementedError
+
+    def div(self, *args: str) -> str:
+        raise NotImplementedError
+
+    def h1(self, name: str) -> str:
+        raise NotImplementedError
+
+    def h2(self, name: str) -> str:
+        raise NotImplementedError
+
+    def h3(self, name: str) -> str:
+        raise NotImplementedError
+
+    def h4(self, name: str) -> str:
+        raise NotImplementedError
+
+    def hr(self) -> str:
+        raise NotImplementedError
+
+    def new_line(self) -> str:
+        raise NotImplementedError