┌─────────────────────────────────────────────────────────────────────────────┐
│                    DOCUMENTATION CATEGORIES                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. TECHNICAL DOCUMENTATION                                                │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • For developers and technical users                                │   │
│  │ • Explains architecture, APIs, code                                │   │
│  │ • Examples: API docs, architecture diagrams, code comments          │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  2. USER DOCUMENTATION                                                      │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • For end users                                                      │   │
│  │ • Explains how to use the product                                   │   │
│  │ • Examples: User guides, tutorials, FAQs                            │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  3. ACADEMIC DOCUMENTATION                                                 │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • For academic submission                                           │   │
│  │ • Explains research, methodology, findings                         │   │
│  │ • Examples: Research papers, dissertations                          │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  4. PROJECT DOCUMENTATION                                                  │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │ • For project management                                            │   │
│  │ • Explains scope, timeline, progress                               │   │
│  │ • Examples: Project plans, progress reports                         │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

# ===================================================================
# MODULE 10, LESSON 6: DOCUMENTATION AND REPORTING
# ===================================================================

import pandas as pd
import matplotlib.pyplot as plt
from typing import Dict, List
import warnings
warnings.filterwarnings('ignore')

print("="*70)
print("DOCUMENTATION AND REPORTING")
print("="*70)

# ----------------------------------------------------------------
# PART A: DOCUMENTATION TEMPLATE
# ----------------------------------------------------------------

print("\n" + "-"*60)
print("PART A: Documentation Template")
print("-"*60)

class DocumentationTemplate:
    """
    Template for capstone project documentation.
    """
    def __init__(self, title: str, author: str, date: str):
        self.title = title
        self.author = author
        self.date = date
        self.sections = {}
        self.appendices = {}
    
    def add_section(self, title: str, content: str):
        self.sections[title] = content
    
    def add_appendix(self, title: str, content: str):
        self.appendices[title] = content
    
    def generate(self) -> str:
        """Generate the full documentation."""
        output = f"# {self.title}\n\n"
        output += f"**Author:** {self.author}\n\n"
        output += f"**Date:** {self.date}\n\n"
        output += "---\n\n"
        
        output += "## Table of Contents\n\n"
        for i, section in enumerate(self.sections.keys(), 1):
            output += f"{i}. {section}\n"
        if self.appendices:
            output += f"{len(self.sections) + 1}. Appendices\n"
        output += "\n---\n\n"
        
        for section, content in self.sections.items():
            output += f"## {section}\n\n"
            output += f"{content}\n\n"
        
        if self.appendices:
            output += "## Appendices\n\n"
            for title, content in self.appendices.items():
                output += f"### {title}\n\n"
                output += f"{content}\n\n"
        
        return output

# Create template
template = DocumentationTemplate(
    title="Blockchain Capstone Project: DeFi Lending Protocol",
    author="John Doe",
    date="2024-12-01"
)

# Add sections
template.add_section("Introduction", 
    "This document describes the design, implementation, and evaluation of a DeFi lending protocol.\n\nThe project addresses the need for efficient, transparent, and accessible lending in the digital asset space.")

template.add_section("Literature Review", 
    "Existing DeFi lending protocols have demonstrated the viability of permissionless lending. However, challenges remain in capital efficiency, risk management, and user experience.\n\nKey references:\n• Aave V3\n• Compound V3\n• Ethereum Improvement Proposals")

template.add_section("Methodology", 
    "The project follows an agile development methodology with iterative design and testing cycles.\n\nDevelopment phases:\n1. Requirements Analysis\n2. Smart Contract Design\n3. Implementation\n4. Testing\n5. Deployment")

template.add_section("Results", 
    "The protocol was successfully deployed to the Sepolia testnet.\n\nKey metrics:\n• Gas usage: Optimised to reduce costs by 30%\n• Test coverage: 92%\n• Security: No critical vulnerabilities identified")

template.add_section("Conclusion", 
    "The project demonstrates the potential for efficient and secure DeFi lending.\n\nFuture work:\n• Cross-chain compatibility\n• Advanced risk management\n• Enhanced user experience")

# Add appendix
template.add_appendix("Code Snippets", 
    "```solidity\n// Example smart contract code\nfunction lend(address borrower, uint256 amount) public {\n    // Implementation details\n}\n```")

# Generate document
document = template.generate()
print("Documentation Template Generated:")
print("\n" + "="*50)
print(document[:1000] + "...")
print("="*50)

# ----------------------------------------------------------------
# PART B: REFERENCING STYLE GUIDE
# -----------------------------------------------------------------

print("\n" + "-"*60)
print("PART B: Referencing Style Guide")
print("-"*60)

reference_data = {
    'Source Type': ['Journal Article', 'Book', 'White Paper', 'Website', 'GitHub', 'Report'],
    'Format': [
        'Author, A. (Year). Title. Journal, Volume(Issue), Pages.',
        'Author, A. (Year). Title. Publisher.',
        'Author, A. (Year). Title. URL.',
        'Author, A. (Year). Title. URL. Accessed: Date.',
        'Author. Repository Name. GitHub. URL.',
        'Organisation. (Year). Title. URL.'
    ],
    'Example': [
        'Nakamoto, S. (2008). Bitcoin: A Peer-to-Peer Electronic Cash System.',
        'Buterin, V. (2020). Ethereum: A Next-Generation Smart Contract Platform.',
        'Wood, G. (2014). Ethereum: A Secure Decentralised Generalised Transaction Ledger.',
        'Ethereum Foundation. (2024). Ethereum Development. ethereum.org.',
        'OpenZeppelin. OpenZeppelin Contracts. GitHub.',
        'BIS. (2023). CBDC: A Framework for Implementation.'
    ]
}

reference_df = pd.DataFrame(reference_data)
print(reference_df.to_string(index=False))

# ----------------------------------------------------------------
# PART C: DOCUMENTATION CHECKLIST
# -----------------------------------------------------------------

print("\n" + "-"*60)
print("PART C: Documentation Checklist")
print("-"*60)

doc_checklist = {
    "Structure": [
        "Title page",
        "Abstract/Executive summary",
        "Table of contents",
        "List of figures/tables",
        "Introduction",
        "Literature review",
        "Methodology",
        "Results/Implementation",
        "Discussion",
        "Conclusion",
        "References",
        "Appendices"
    ],
    "Content": [
        "Clear problem statement",
        "Well-defined objectives",
        "Comprehensive literature review",
        "Detailed methodology",
        "Complete results/implementation",
        "Critical discussion",
        "Actionable recommendations",
        "Proper citations"
    ],
    "Formatting": [
        "Consistent heading styles",
        "Page numbers",
        "Clear font and spacing",
        "Figures and tables labelled",
        "Proper references",
        "No spelling/grammar errors"
    ],
    "Technical": [
        "Code documented",
        "APIs documented",
        "Architecture diagrams",
        "Deployment instructions",
        "Testing documentation"
    ]
}

for category, items in doc_checklist.items():
    print(f"\n{category.upper()}:")
    for item in items:
        print(f"  □ {item}")

# ----------------------------------------------------------------
# PART D: SUMMARY AND RECOMMENDATIONS
# -----------------------------------------------------------------

print("\n" + "="*70)
print("PART D: Summary and Recommendations")
print("="*70)

print("""
Documentation and Reporting – Key Takeaways:

1. Documentation types: technical (developers), user (end users), academic (submission), project (management).
2. Best practices: know your audience, be clear, use examples, be consistent.
3. Report structure: title page, abstract, introduction, literature review, methodology, results, discussion, conclusion, references.
4. Academic writing: formal tone, third person, evidence-based, critical analysis.
5. Smart contract documentation: Natspec comments, architecture diagrams, API reference.
6. Citation styles: APA, MLA, Chicago, IEEE, Harvard, Vancouver.

Documentation Checklist:
  - Structure the report properly.
  - Write clearly and concisely.
  - Use proper citations.
  - Include technical documentation.
  - Proofread carefully.
  - Format consistently.

Recommendations:
  - Start documentation early.
  - Use templates for consistency.
  - Get feedback from peers.
  - Proofread multiple times.
  - Follow style guidelines.
  - Include all required sections.
""")