Cách sử dụng phpdocumentor

THỰC NGHIỆM. Bất cứ điều gì liên quan đến việc tạo Hướng dẫn, trong thư mục này hoặc ở nơi khác, đều được coi là thử nghiệm và có thể bị thay đổi hoặc xóa mà không cần thông báo hoặc cân nhắc cho BC

Thư viện Hướng dẫn của phpDocumentor lấy tài liệu viết tay trong kho lưu trữ mã, tạo AST từ đó và cung cấp cho trình kết xuất để tạo đầu ra mong muốn

Là một phần của mục tiêu này, bản thân thư viện Hướng dẫn giống như một khung nơi bạn có thể bổ sung hỗ trợ cho định dạng đầu vào, chẳng hạn như Văn bản được cấu trúc lại và bổ sung định dạng đầu ra để xuất ra, chẳng hạn như HTML

Định dạng được hỗ trợ

Đầu vào

Vì đây là thành phần mới nên số lượng định dạng có hạn và có thể mở rộng trong tương lai

• Văn bản được cấu trúc lại;
• đánh dấu;

đầu ra

Vì đây là thành phần mới nên số lượng định dạng có hạn và có thể mở rộng trong tương lai

• HTML
• Mủ cao su;

Cách sử dụng

Lưu ý . vì thư viện này vẫn đang được phát triển nên các hướng dẫn này có thể thay đổi trước khi phát hành

Bạn có thể sử dụng thư viện này theo 2 cách

1. Phân tích cú pháp (một loạt) tài liệu dựa trên đánh dấu thành AST
2. Kết xuất AST đã nói ở trên thành các tài liệu HTML chẳng hạn

Sự phân chia này là theo thiết kế để cho phép người tiêu dùng triển khai cơ chế lưu vào bộ nhớ đệm, triển khai các quy trình kết xuất của riêng họ và các hoạt động kinh doanh tiện lợi khác

phân tích cú pháp

Với trình phân tích cú pháp của Hướng dẫn, bạn có thể chuyển đổi văn bản của ngôn ngữ đánh dấu thành AST. AST này có thể được sử dụng trong công cụ khác để giải thích nó hoặc định dạng lại nó hoặc nó có thể được chuyển qua Trình kết xuất của Hướng dẫn viên để tạo tài liệu kết xuất từ ​​nó

Bước 1. Cài đặt gói ngôn ngữ

Về bản thân, Trình phân tích cú pháp của Hướng dẫn viên không biết phân tích ngôn ngữ nào và loại ngôn ngữ nào. Để sử dụng nó, bạn cũng cần cài đặt gói dành riêng cho ngôn ngữ;

Bước 2. Khởi tạo trình phân tích cú pháp

// Define which language conversions are supported by Guides
$markupParsers = [
    new \phpDocumentor\Guides\RestructuredText\MarkupLanguageParser(...),
];

// Define which output formats are supported by Guides
$outputFormats = new OutputFormats(
    [
        new \phpDocumentor\Guides\RestructuredText\HTML\HTMLFormat(...),
    ]
);

// Declare how URLs are generated
$urlGenerator = new \phpDocumentor\Guides\UrlGenerator();

// Instantate the Parser itself, optionally with a PSR-3 compliant logger at $logger.
$parser = new Parser($urlGenerator, $outputFormats, $markupParsers, $logger);

Bước 3. Chuẩn bị phân tích cú pháp nhiều tệp (tùy chọn)

Khi bạn muốn phân tích cú pháp một loạt tệp đi cùng nhau hoặc có tham chiếu đến nội dung hoặc tệp bên ngoài khác;

Lưu ý . Có thể bỏ qua bước này nếu bạn chỉ muốn phân tích cú pháp một khối văn bản độc lập. Nếu bạn bỏ qua bước này, nó sẽ được ngầm thực hiện bằng phương pháp parse() với thư mục làm việc hiện tại, không có đường dẫn nguồn và đích; .

// A Table of Contents-like collection; only need to instantiated once for all files.
// This collection will be populated by the Parser with metadata derived from the parsed file.
$metas = new Metas();

// The filesystem to load/include files from, can be any FlySystem v1 
// Adapter: https://flysystem.thephpleague.com/v1/docs/
$filesystem = new Filesystem(new Local('/home/myUser/projects/my/project'));

// Path of this file in the filesystem, helps to calculate relative source paths from; 
// i.e. /home/myUser/projects/my/project/docs
$sourcePath = 'docs';  

// Path of this file on the destination location, helps to calculate relative destination paths; 
// i.e. https://docs.myproject.com/latest 
$destinationPath = 'latest'; 

// The current filename, important: omit the extension!
$fileName = 'index';

// DO IT!
$parser->prepare($metas, $filesystem, $sourcePath, $destinationPath, $fileName);

Bước 4. Lợi nhuận. Phân tích nội dung tập tin

Khi bạn đã sẵn sàng, chỉ cần chuyển văn bản đánh dấu mà bạn muốn phân tích cú pháp và định dạng của nó (hoặc bỏ qua nếu định dạng là rst)

Phương pháp phân tích cú pháp sau đó sẽ bắt đầu diễn giải văn bản đã cho và trả về một thể hiện của \phpDocumentor\Guides\Nodes\DocumentNode với

$text = 'My *Awesome* file';

// What format is this file is? (default: "rst")
$inputFormat = 'rst';

$document = $parser->parse($text, $inputFormat);

TODO

Vì thư viện này đang được phát triển nên hiện tại nó vẫn có các phụ thuộc vào gói chính phpDocumentor hoặc giữa trình phân tích cú pháp và trình kết xuất. Có nhiều câu lệnh TODO trong mã cần được giải quyết trước khi gói này có thể được thăng cấp lên một thư viện độc lập

Tách thư viện Hướng dẫn thành các gói định dạng đầu vào

Việc tách thư viện Hướng dẫn thành các gói riêng biệt gần đây đã được bắt đầu, trong gói này vẫn có sự trùng lặp với gói bổ trợ Văn bản được cấu trúc lại và cần được giải quyết. Các đoạn mã sau đây cần được cấu trúc lại để trở thành định dạng đầu vào bất khả tri

1. Bảng (Nút)
2. Khoảng cách (Nút)

Trích xuất các định dạng đầu ra

Các định dạng đầu ra / kết xuất hiện vẫn nằm trong gói này và các mẫu nhánh nằm trong gói chính của phpDocumentor. Twig dự kiến ​​vẫn là phương pháp cốt lõi để tạo đầu ra, nhưng chúng tôi muốn trích xuất các định dạng riêng lẻ (HTML, LaTeX, v.v. ) thành các gói riêng biệt