Add ability to output docs as markdown and pdf

Author: robtaylor

docs/assemble-md.py

@@ -0,0 +1,75 @@
+import os
+import sys
+import markdown2
+
+def adjust_image_paths(content, current_file_dir, output_base_dir):
+    """
+    Adjust relative image paths to be relative to the output base directory and use forward slashes.
+    """
+    lines = content.split('\n')
+    for i, line in enumerate(lines):
+        if '](' in line:
+        #if '![' in line and '](' in line:
+            start_link = line.find('](') + 2
+            end_link = line.find(')', start_link)
+            relative_path = line[start_link:end_link]
+            if not os.path.isabs(relative_path):
+                # Calculate the relative path from the current file directory to the image
+                image_path = os.path.normpath(os.path.join(current_file_dir, relative_path))
+                relative_to_output = os.path.relpath(image_path, output_base_dir)
+                # Convert backslashes to forward slashes
+                relative_to_output = relative_to_output.replace('\\', '/')
+                lines[i] = line[:start_link] + relative_to_output + line[end_link:]
+    return '\n'.join(lines)
+
+def assemble_markdown_files(index_file, output_file_base):
+    markdown_content = ""
+    toc_content = ""
+    base_path = os.path.dirname(os.path.abspath(index_file))
+    output_base_dir = os.path.dirname(os.path.abspath(output_file_base + '.md'))
+
+    with open(index_file, 'r') as file:
+        lines = file.readlines()
+    
+    for line in lines:
+        if ' [' in line:
+            start_link = line.find('(') + 1
+            end_link = line.find(')')
+            file_link = line[start_link:end_link].strip()
+            file_path = os.path.normpath(os.path.join(base_path, file_link))
+
+            # Generate clean anchors for ToC links
+            anchor_link = f'#{os.path.basename(file_link).replace(".md", "").replace(" ", "-").lower()}'
+            toc_line = line.replace(file_link, anchor_link)
+            toc_content += toc_line
+            
+            # Check file type and skip non-markdown files
+            if file_link.lower().endswith('.md') and os.path.exists(file_path):
+                with open(file_path, 'r') as infile:
+                    file_contents = infile.read()
+                    file_contents = adjust_image_paths(file_contents, os.path.dirname(file_path), output_base_dir)
+                    file_contents = file_contents.replace("\n#", "\n##")  # Downgrade headers
+                    markdown_content += f"\n<a id='{os.path.basename(file_link).replace('.md', '').replace(' ', '-').lower()}'></a>\n\n----\n\n"
+                    markdown_content += file_contents + '\n'
+            elif not file_link.lower().endswith('.md'):
+                toc_content += f" (External file not included in compilation)\n"
+            else:
+                markdown_content += f"# File not found: {file_link}\n\n"
+        else:
+            toc_content += line
+            markdown_content += line
+
+    complete_markdown = toc_content + markdown_content
+    with open(output_file_base + '.md', 'w') as outfile:
+        outfile.write(complete_markdown)
+
+if __name__ == "__main__":
+    index_filename = 'README.md'
+    output_filename_base = 'Complete'
+    
+    if len(sys.argv) > 1:
+        index_filename = sys.argv[1]
+    if len(sys.argv) > 2:
+        output_filename_base = sys.argv[2]
+    
+    assemble_markdown_files(index_filename, output_filename_base)

docs/conf.py

@@ -17,6 +17,8 @@
     "sphinx.ext.napoleon",
     "sphinx_rtd_theme",
     "sphinxcontrib.yowasp_wavedrom",
+    "sphinx_markdown_builder",
+    "rst2pdf.pdfbuilder",
 ]
 
 with open(".gitignore") as f:
@@ -57,3 +59,7 @@
 .. role:: py(code)
    :language: python
 """
+
+pdf_documents = [
+    ('index', 'amaranth-soc', project, ' Amaranth project contributors'),
+]

pyproject.toml

@@ -13,8 +13,9 @@ license = {file = "LICENSE.txt"}
 
 requires-python = "~=3.8"
 dependencies = [
-  # this version requirement needs to be synchronized with the one in .github/workflows/main.yml
-  "amaranth>=0.5,<0.6",
+    # this version requirement needs to be synchronized with the one in .github/workflows/main.yml
+    "amaranth>=0.5,<0.6",
+    "markdown2>=2.5.1",
 ]
 
 [project.urls]
@@ -40,6 +41,8 @@ docs = [
   "sphinxcontrib-yowasp-wavedrom~=1.0",
   "sphinx-rtd-theme~=1.2",
   "sphinx-autobuild",
+  "sphinx-markdown-builder>=0.6.7",
+  "rst2pdf>=0.102",
 ]
 
 [tool.pdm.scripts]
@@ -50,6 +53,16 @@ test-docs.cmd = "sphinx-build -b doctest docs docs/_build"
 
 document.cmd = "sphinx-build docs docs/_build"
 document-live.cmd = "sphinx-autobuild docs docs/_build --watch amaranth_soc"
+document-md.composite = [
+    "sphinx-build -M markdown docs docs/_build",
+    "docs/assemble-md.py docs/_build/markdown/index.md docs/amaranth-soc.md",
+    "echo Markdown documentation created at docs/amaranth-soc.md"
+    ]
+document-pdf.composite = [
+    "sphinx-build -b pdf docs docs/_build",
+    "cp docs/_build/amaranth-soc.pdf docs",
+    "echo PDF documentation created at docs/amaranth-soc.pdf"
+]
 
 coverage-text.cmd = "python -m coverage report"
 coverage-html.cmd = "python -m coverage html"