Updated manage docs script
This commit is contained in:
parent
9ac6750246
commit
bbec991566
|
|
@ -0,0 +1,109 @@
|
|||
import os
|
||||
import re
|
||||
import sys
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
filenames = [
|
||||
"docs/changes.md",
|
||||
"docs/overview.md",
|
||||
"docs/lexical_structure.md",
|
||||
"docs/primitive_types.md",
|
||||
"docs/basic_operations.md",
|
||||
"docs/functions.md",
|
||||
"docs/control_flow.md",
|
||||
"docs/data_structures.md",
|
||||
"docs/type_system.md",
|
||||
"docs/trait_system.md",
|
||||
"docs/generic_programming.md",
|
||||
"docs/advanced_topics.md",
|
||||
"docs/standard_library.md",
|
||||
"docs/complete_trait_reference.md",
|
||||
"docs/complete_operator_reference.md",
|
||||
"docs/grammar_summary.md",
|
||||
"docs/module_system.md",
|
||||
"docs/memory_management.md",
|
||||
"docs/examples_and_tutorials.md",
|
||||
]
|
||||
|
||||
def remove_front_matter(content):
|
||||
"""Remove YAML front matter (--- ... ---) from markdown content."""
|
||||
pattern = r'^---\n.*?\n---\n'
|
||||
return re.sub(pattern, '', content, flags=re.DOTALL)
|
||||
|
||||
def extract_front_matter(content):
|
||||
"""Extract YAML front matter from markdown content."""
|
||||
match = re.match(r'^---\n(.*?)\n---\n', content, flags=re.DOTALL)
|
||||
return match.group(1).strip() if match else None
|
||||
|
||||
def read_file_list(input_arg):
|
||||
"""Return list of files either from arguments or a text file of paths."""
|
||||
p = Path(input_arg)
|
||||
if p.is_file() and p.suffix == '.txt':
|
||||
with p.open(encoding='utf-8') as f:
|
||||
return [line.strip() for line in f if line.strip()]
|
||||
return [input_arg]
|
||||
|
||||
def combine_markdown(file_inputs, output_combined, output_meta_json):
|
||||
"""Combine multiple markdown files into one, skipping front matter."""
|
||||
files = []
|
||||
for f in file_inputs:
|
||||
files.extend(read_file_list(f))
|
||||
|
||||
combined = []
|
||||
meta_info = {}
|
||||
|
||||
for file in files:
|
||||
file_path = Path(file)
|
||||
if not file_path.exists():
|
||||
print(f"⚠️ Skipping missing file: {file}")
|
||||
continue
|
||||
|
||||
text = file_path.read_text(encoding='utf-8')
|
||||
front_matter = extract_front_matter(text)
|
||||
if front_matter:
|
||||
meta_info[file_path.name] = front_matter
|
||||
cleaned = remove_front_matter(text).strip()
|
||||
combined.append(f"<!-- START {file_path.name} -->\n{cleaned}\n\n<!-- END {file_path.name} -->\n")
|
||||
# combined.append(f"{cleaned}\n")
|
||||
|
||||
Path(output_combined).write_text("\n".join(combined), encoding='utf-8')
|
||||
Path(output_meta_json).write_text(json.dumps(meta_info, indent=2), encoding='utf-8')
|
||||
|
||||
print(f"✅ Combined file saved as: {output_combined}")
|
||||
print(f"✅ Metadata JSON saved as: {output_meta_json}")
|
||||
|
||||
def split_by_h2(input_combined, output_dir):
|
||||
"""Split a combined markdown file by H2 sections (## Heading)."""
|
||||
content = Path(input_combined).read_text(encoding='utf-8')
|
||||
sections = re.split(r'(?=^## )', content, flags=re.MULTILINE)
|
||||
|
||||
os.makedirs(output_dir, exist_ok=True)
|
||||
for i, section in enumerate(sections):
|
||||
if not section.strip():
|
||||
continue
|
||||
title_match = re.match(r'##\s*(.+)', section)
|
||||
if title_match:
|
||||
filename = re.sub(r'[^\w\-]+', '_', title_match.group(1)).strip('_') + ".md"
|
||||
else:
|
||||
filename = f"part_{i+1}.md"
|
||||
Path(output_dir, filename).write_text(section.strip() + "\n", encoding='utf-8')
|
||||
print(f"Created: {filename}")
|
||||
|
||||
if __name__ == "__main__":
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage:")
|
||||
print(" Combine files: python manage_docs.py combine")
|
||||
print(" Split by H2: python manage_docs.py split")
|
||||
|
||||
command = sys.argv[1].lower()
|
||||
|
||||
if command == "combine":
|
||||
combine_markdown(filenames, "stack_lang_spec.md", "metadata.json")
|
||||
|
||||
elif command == "split":
|
||||
split_by_h2("stack_lang_spec.md", "docs")
|
||||
|
||||
else:
|
||||
print("Unknown command. Use 'combine' or 'split'.")
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
{
|
||||
"changes.md": "Title: Stack Language Specification\nPrev:\nNext:",
|
||||
"overview.md": "Title: 1 Overview\nPrev: Index\nNext: Lexical Structure",
|
||||
"lexical_structure.md": "Title: 2 Lexical Structure\nPrev: Overview\nNext: Primitive Types",
|
||||
"primitive_types.md": "Title: 3 Primitive Types\nPrev: Lexical Structure\nNext: Basic Operations",
|
||||
"basic_operations.md": "Title: 4 Basic Operations\nPrev: Primitive Types\nNext: Functions",
|
||||
"functions.md": "Title: 5 Functions\nPrev: Basic Operations\nNext: Control Flow",
|
||||
"control_flow.md": "Title: 6 Control Flow\nPrev: Functions\nNext: Data Structures",
|
||||
"data_structures.md": "Title: 7 Data Structures\nPrev: Control Flow\nNext: Type System",
|
||||
"type_system.md": "Title: 8 Type System\nPrev: Data Structures\nNext: Trait System",
|
||||
"trait_system.md": "Title: 9 Trait System\nPrev: Type System\nNext: Generic Programming",
|
||||
"generic_programming.md": "Title: 10 Generic Programming\nPrev: Trait System\nNext: Advanced Topics",
|
||||
"advanced_topics.md": "Title: 11 Advanced Topics\nPrev: Generic Programming\nNext: Standard Library",
|
||||
"standard_library.md": "Title: A Standard Library\nPrev: Advanced Topics\nNext: Complete Trait Reference",
|
||||
"complete_trait_reference.md": "Title: B Complete Trait Reference\nPrev: Standard Library\nNext: Complete Operator Reference",
|
||||
"complete_operator_reference.md": "Title: C Complete Operator Reference\nPrev: Complete Trait Reference\nNext: Grammar Summary",
|
||||
"grammar_summary.md": "Title: D Grammar Summary\nPrev: Complete Operator Reference\nNext: Module System",
|
||||
"module_system.md": "Title: E Module System\nPrev: Grammar Summary\nNext: Memory Management",
|
||||
"memory_management.md": "Title: F Memory Management\nPrev: Module System\nNext: Examples and Tutorials",
|
||||
"examples_and_tutorials.md": "Title: G Examples & Tutorials\nPrev: Memory Management\nNext:"
|
||||
}
|
||||
|
|
@ -1,3 +1,4 @@
|
|||
<!-- START changes.md -->
|
||||
# Stack Language Specification
|
||||
|
||||
**Version**: 0.8
|
||||
|
|
@ -72,6 +73,9 @@
|
|||
|
||||
---
|
||||
|
||||
<!-- END changes.md -->
|
||||
|
||||
<!-- START overview.md -->
|
||||
## 1. Overview
|
||||
|
||||
A statically-typed, stack-based language with pure postfix notation combining the execution model of HP's RPL, the type system of C and Rust, and modern array operations from Uiua.
|
||||
|
|
@ -144,6 +148,9 @@ This specification is organized to support both learning and reference:
|
|||
|
||||
---
|
||||
|
||||
<!-- END overview.md -->
|
||||
|
||||
<!-- START lexical_structure.md -->
|
||||
## 2. Lexical Structure
|
||||
|
||||
### 2.1 Comments
|
||||
|
|
@ -216,6 +223,9 @@ false
|
|||
|
||||
---
|
||||
|
||||
<!-- END lexical_structure.md -->
|
||||
|
||||
<!-- START primitive_types.md -->
|
||||
## 3. Primitive Types
|
||||
|
||||
The language provides several built-in primitive types for common values:
|
||||
|
|
@ -250,6 +260,9 @@ Raw pointers (`ptr`) are a future feature. See [Appendix F](./memory_management.
|
|||
|
||||
---
|
||||
|
||||
<!-- END primitive_types.md -->
|
||||
|
||||
<!-- START basic_operations.md -->
|
||||
## 4. Basic Operations
|
||||
|
||||
### 4.1 Stack Operations
|
||||
|
|
@ -378,6 +391,9 @@ Bitwise operations work on integer types:
|
|||
|
||||
---
|
||||
|
||||
<!-- END basic_operations.md -->
|
||||
|
||||
<!-- START functions.md -->
|
||||
## 5. Functions
|
||||
|
||||
Functions are user-defined procedures that encapsulate reusable code. They are the primary abstraction mechanism in the language.
|
||||
|
|
@ -511,6 +527,9 @@ The `lambda` operator converts a TokenString into a callable code block that can
|
|||
|
||||
---
|
||||
|
||||
<!-- END functions.md -->
|
||||
|
||||
<!-- START control_flow.md -->
|
||||
## 6. Control Flow
|
||||
|
||||
### 6.1 Conditionals
|
||||
|
|
@ -664,6 +683,9 @@ result {
|
|||
|
||||
---
|
||||
|
||||
<!-- END control_flow.md -->
|
||||
|
||||
<!-- START data_structures.md -->
|
||||
## 7. Data Structures
|
||||
|
||||
### 7.1 Structs
|
||||
|
|
@ -815,6 +837,9 @@ These operations take TokenString arguments containing function bodies:
|
|||
|
||||
---
|
||||
|
||||
<!-- END data_structures.md -->
|
||||
|
||||
<!-- START type_system.md -->
|
||||
## 8. Type System
|
||||
|
||||
### 8.1 Types vs Traits
|
||||
|
|
@ -967,6 +992,9 @@ Option<Point<f64>> // Option containing a Point of f64s
|
|||
|
||||
---
|
||||
|
||||
<!-- END type_system.md -->
|
||||
|
||||
<!-- START trait_system.md -->
|
||||
## 9. Trait System
|
||||
|
||||
### 9.1 What are Traits
|
||||
|
|
@ -1180,6 +1208,9 @@ This section provides a brief overview of all standard traits. For complete defi
|
|||
|
||||
---
|
||||
|
||||
<!-- END trait_system.md -->
|
||||
|
||||
<!-- START generic_programming.md -->
|
||||
## 10. Generic Programming
|
||||
|
||||
### 10.1 Type Parameters
|
||||
|
|
@ -1353,6 +1384,9 @@ When inheriting from generic traits, you must either:
|
|||
|
||||
---
|
||||
|
||||
<!-- END generic_programming.md -->
|
||||
|
||||
<!-- START advanced_topics.md -->
|
||||
## 11. Advanced Topics
|
||||
|
||||
### 11.1 Dynamic Code Evaluation
|
||||
|
|
@ -1460,6 +1494,9 @@ The standard library provides I/O, string operations, type conversions, and util
|
|||
|
||||
---
|
||||
|
||||
<!-- END advanced_topics.md -->
|
||||
|
||||
<!-- START standard_library.md -->
|
||||
## Appendix A: Standard Library
|
||||
|
||||
This appendix provides a complete alphabetical reference of all standard library functions and operations.
|
||||
|
|
@ -1802,6 +1839,9 @@ This appendix provides a complete alphabetical reference of all standard library
|
|||
|
||||
---
|
||||
|
||||
<!-- END standard_library.md -->
|
||||
|
||||
<!-- START complete_trait_reference.md -->
|
||||
## Appendix B: Complete Trait Reference
|
||||
|
||||
This appendix contains all built-in trait definitions with complete documentation, organized alphabetically.
|
||||
|
|
@ -2571,6 +2611,9 @@ This appendix contains all built-in trait definitions with complete documentatio
|
|||
|
||||
---
|
||||
|
||||
<!-- END complete_trait_reference.md -->
|
||||
|
||||
<!-- START complete_operator_reference.md -->
|
||||
## Appendix C: Complete Operator Reference
|
||||
|
||||
This appendix provides a complete alphabetical reference of all operators in the language.
|
||||
|
|
@ -3117,6 +3160,9 @@ This appendix provides a complete alphabetical reference of all operators in the
|
|||
|
||||
---
|
||||
|
||||
<!-- END complete_operator_reference.md -->
|
||||
|
||||
<!-- START grammar_summary.md -->
|
||||
## Appendix D: Grammar Summary
|
||||
|
||||
This appendix provides a concise grammar reference. For complete specifications of language constructs (fn, struct, trait, impl, etc.), see the `::Implementable` trait in Appendix B.
|
||||
|
|
@ -3222,6 +3268,9 @@ Language constructs (fn, struct, trait, impl, enum, union, inher) are defined by
|
|||
|
||||
---
|
||||
|
||||
<!-- END grammar_summary.md -->
|
||||
|
||||
<!-- START module_system.md -->
|
||||
## Appendix E: Module System (Future)
|
||||
|
||||
**Current State**: All standard library functions and traits are automatically in scope.
|
||||
|
|
@ -3268,6 +3317,9 @@ Language constructs (fn, struct, trait, impl, enum, union, inher) are defined by
|
|||
|
||||
---
|
||||
|
||||
<!-- END module_system.md -->
|
||||
|
||||
<!-- START memory_management.md -->
|
||||
## Appendix F: Memory Management (Future)
|
||||
|
||||
The language specification currently does not include heap memory management. This appendix documents potential future approaches.
|
||||
|
|
@ -3355,6 +3407,9 @@ This would provide stronger type safety but add complexity to the type checker.
|
|||
|
||||
---
|
||||
|
||||
<!-- END memory_management.md -->
|
||||
|
||||
<!-- START examples_and_tutorials.md -->
|
||||
## Appendix G: Examples & Tutorials
|
||||
|
||||
### G.1 Tutorial: First Steps
|
||||
|
|
@ -3781,3 +3836,5 @@ dup ::x get print // Prints: 3.0
|
|||
```
|
||||
|
||||
---
|
||||
|
||||
<!-- END examples_and_tutorials.md -->
|
||||
|
|
|
|||
Loading…
Reference in New Issue