Nhân sư cho tài liệu mã php

Question

Nhân sư là một thư viện Python để tạo tài liệu đẹp từ một tập hợp các tệp văn bản được định dạng lại. Không phải công cụ được sử dụng để tìm kiếm toàn văn

Tôi cũng hoàn toàn nhận thức được các công cụ doxygen/phpdoc. Tôi đang cố gắng tìm ra nếu có một cách để sử dụng Sphinx để tài liệu dự án php? hoặc thậm chí bất kỳ ngôn ngữ không phải python nào khác?

http://sphinx.pocoo.org/

Answer 1

Sphinx và phần còn lại có thể được sử dụng như công cụ tài liệu chung, trong kinh nghiệm của tôi. Không có gì về Sphinx mà bắt buộc bạn chỉ sử dụng nó cho các dự án dựa trên Python. Ví dụ, trong công việc của tôi, tôi đã sử dụng nó để xây dựng một hướng dẫn sử dụng và một tham chiếu API XML-RPC. Trong cả hai trường hợp, tôi không sử dụng cho sphinx.ext.autodoc hoặc các tính năng bổ sung cụ thể khác của Python. Tài liệu được viết "bằng tay", với hầu hết các chỉ thị ReST chung chung, chứ không phải chỉ thị đặc biệt do Sphinx cung cấp. Đối với những gì nó có giá trị, tôi vẫn chưa cần thiết để tạo ra một chỉ thị ReST tùy chỉnh cho tài liệu không Python.

Thậm chí nếu bạn đang làm việc với dự án PHP, tôi nghĩ bạn sẽ thấy Nhân sư hữu ích. Ví dụ hầu hết các chỉ thị được cung cấp bởi the module specific markup thực sự là khá chung chung. Tôi không thấy lý do tại sao bạn không thể hoặc sẽ không sử dụng các cấu trúc này để ghi lại nội dung từ các ngôn ngữ khác ngoài Python. Tương tự như vậy, Sphinx làm cho nó khá dễ dàng để show code examples in other languages. Thậm chí còn có một giá trị cấu hình để thay đổi mặc định thành bất kỳ ngôn ngữ nào mà Pygments hỗ trợ (bao gồm cả PHP). Nếu bạn cảm thấy đặc biệt đầy tham vọng, bạn thậm chí có thể create a Sphinx extension để lấy thứ gì đó có liên quan từ mã PHP của bạn.

Tất cả những gì đã nói, hãy nhớ xem xét đối tượng cho dự án tài liệu của bạn. Trong khi tôi nghĩ Sphinx là một công cụ tuyệt vời và muốn giới thiệu nó cho một loạt các dự án tài liệu, nếu khán giả của bạn đang mong đợi một cái gì đó khác, hãy chú ý đến điều đó. Ví dụ, nếu bạn đang viết tư liệu cho một dự án Java, phần lớn khán giả của bạn có thể mong đợi các tài liệu kiểu Javadoc. Nếu bạn đi chệch khỏi kỳ vọng đó, hãy đảm bảo rằng nó không chỉ cho các cú đá (ví dụ, nó cung cấp cho bạn các tài liệu tốt hơn bạn muốn) và chuẩn bị (ngắn gọn) làm cho trường hợp cho những gì bạn đã làm khác (ví dụ: Câu trả lời hoặc giới thiệu câu hỏi thường gặp).

Cuối cùng, mọi tài liệu đều tốt hơn không có tài liệu, bất kể công cụ được sử dụng để tạo chúng. Sử dụng bất kỳ công cụ nào giúp bạn, nếu đó là sự khác biệt giữa việc đưa ra thứ gì đó ở đó và không.

Answer 2

Chỉ cần phát hành cách đây vài ngày: http://mark-story.com/posts/view/sphinx-phpdomain-released

Answer 3

Dự án Doctrine, một ORM cho PHP, sử dụng Sphinx để tạo ra tài liệu trực tuyến của họ tại www.doctrine-project.org. Họ sử dụng một pygment tùy chỉnh cho PHP. Tài liệu có sẵn trên Github tại https://github.com/doctrine/orm-documentation. Nó bao gồm tệp css pygment PHP tùy chỉnh.

Ngoài ra python-pygments gói đi kèm với nhiều phong cách pygment mà bạn có thể thử bằng cách thay đổi pygments_style = giá trị trong nhân sư của bạn conf.py tập tin cấu hình. Ví dụ, để thử làm nổi bật sytle pastie, mà là một phần của python-pygments, bạn sử dụng

pygments_sytle = 'pastie' 

Answer 4

CakePHP đang sử dụng Sphinx cho tài liệu mới của mình, và tôi đã viết phpdomain cho nhân sư. Mặc dù không có cách nào để tự động bao gồm các khối tài liệu php của bạn vào nhân sư, nhưng tôi vẫn nghĩ đó là một trong những công cụ tạo tài liệu tốt hơn có sẵn. Tuyệt vời của nó cho tài liệu phong cách tường thuật hơn.Nhưng với phpdomain bạn cũng có thể tạo tài liệu api.

Answer 5

Theo như tôi quan tâm, bạn có thể ghi lại bất kỳ cú pháp nào trong Sphinx khi bạn không giới hạn bản thân bằng các ngôn ngữ được hỗ trợ bởi autodoc. Bạn có thể tạo Tham chiếu API đẹp bằng cách sử dụng chỉ thị Sphinx chuẩn như .. class, .. method, .. function và các chỉ thị khác. Chúng hoạt động hoàn hảo ngoài mã nguồn và không yêu cầu bất kỳ thế hệ tự động nào và liên kết với các nguồn.

Bạn cũng có thể tạo ra những lời khuyên nhủ chung với một số lớp học đặc biệt, mà sau này bạn có thể treo vào CSS:

.. admonition Title 
    :class: Ololo 

    This text could be formatted any way you want, using the ``Ololo`` tag. 

Ngoài ra còn có vai trò (họ cho phép các lớp học tùy chỉnh quá) và các phương tiện khác của việc thêm văn bản với một số đặc biệt định dạng, nếu các chỉ thị ban đầu không đủ cho bạn.

Nếu bạn quyết định tạo tài liệu không đồng bộ từ mã nguồn, hãy đảm bảo bạn vô hiệu kiểm tra mức độ mã và các tính năng liên quan đến mã khác trong số conf.py hoặc khi bắt đầu dự án.

PS: Bạn có thể thấy câu trả lời rất hay về các thành phần có lớp tùy chỉnh here.

Answer 6

Như bạn thấy có rất nhiều công cụ để giúp bạn với điều này, nếu không, nếu bạn thực sự cần, check it out:

https://blog.simpleigh.com/2012/08/php-documentation-and-sphinx