Có ai đã sử dụng Sphinx để ghi lại dự án C++ không?

Question

Sphinx là một công cụ tài liệu mới cho Python. Nó trông rất đẹp. Điều tôi đang thắc mắc là:

• Điều này phù hợp cho việc lập tài liệu dự án C++ như thế nào?
• Có công cụ nào để chuyển đổi tài liệu hiện có (ví dụ: doxygen) sang định dạng Sphinx không?
• Có các ví dụ trực tuyến/có thể tải xuống về các dự án C++ sử dụng Sphinx không?
• Bất kỳ mẹo nào từ bất kỳ ai đã sử dụng Nhân sư?

Answer 1

Trước tiên, giữ hai cây thư mục, source và build. Đặt source trong điều khiển phiên bản. Không đặt build trong điều khiển phiên bản, xây dựng lại nó như một phần của quá trình cài đặt.

Thứ hai, đọc http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources.

Sử dụng sphinx-quickstart để tạo cây tài liệu thực hành. Chơi với điều này trong một vài ngày để tìm hiểu cách nó hoạt động. Sau đó sử dụng nó một lần nữa để xây dựng điều thực sự trong các thư mục SVN.

Sắp xếp tài liệu của bạn trong một cây được lên kế hoạch tốt. Một số phần cần "index.rst" cho phần đó, một số thì không. Nó phụ thuộc vào cách "độc lập" phần là.

Cấp cao nhất của chúng tôi index.rst giống như thế này.

.. XXX documentation master file, created by sphinx-quickstart on Wed Dec 31 07:27:45 2008. 

.. include:: overview.inc 

.. _`requirements`: 

Requirements 
============ 

.. toctree:: 
    :maxdepth: 1 

    requirements/requirements 
    requirements/admin 
    requirements/forward 
    requirements/volume 

.. _`architecture`: 

Architecture 
============ 

.. toctree:: 
    :maxdepth: 1 

    architecture/architecture 
    architecture/techstack 
    architecture/webservice_tech 
    architecture/webservice_arch 
    architecture/common_features 
    architecture/linux_host_architecture 

Detailed Designs 
================ 

.. toctree:: 
    :maxdepth: 3 

    design/index 


Installation and Operations 
=========================== 

.. toctree:: 
    :maxdepth: 1 

    deployment/installation 
    deployment/operations 
    deployment/support 
    deployment/load_test_results 
    deployment/reference 
    deployment/licensing 

Programming and API's 
===================== 

.. toctree:: 
    :maxdepth: 2 

    programming/index 

**API Reference**. The `API Reference`_ is generated from the source. 

.. _`API Reference`: ../../../apidoc/xxx/index.html 

.. note:: 
    The API reference must be built with `Epydoc`_. 

    .. _`Epydoc`: http://epydoc.sourceforge.net/ 

Management 
========== 

.. toctree:: 
    :maxdepth: 2 
    :glob: 

    management/* 


Indices and tables 
================== 

* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search` 

SVN Revision 
============ 

:: 

    $Revision: 319 $ 

Lưu ý, chúng tôi không "bao gồm" API, chúng tôi chỉ tham chiếu nó bằng liên kết HTML thông thường.

Nhân sư có một tiện ích rất thú vị, được gọi là automodule, sẽ chọn các tài liệu từ các mô-đun Python.

Cập nhật Vì nhân sư 1.0, C và C++ được hỗ trợ. http://sphinx.pocoo.org/

Answer 2

Hãy xem http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html để biết cách tiếp cận XML.

Answer 3

Như đã đề cập here và here,

• Sphinx có nguồn gốc C++ hỗ trợ có liên quan đến làm nổi bật/định dạng/tham khảo, không phải trong mã khai thác tài liệu
• breathe đã phát triển ra khỏi các cuộc thảo luận mà chrisdew tham chiếu

[Chỉnh sửa được chèn bên dưới]:

Tôi đã thử nghiệm d oxy + hít thở + chuỗi công cụ nhân sư trên một thư viện đa thư viện 10 + C++ bao gồm 10 mô-đun/tên miền khác nhau.đáy dòng của tôi là:

1. chưa hoàn toàn có thể sử dụng
2. nhưng tiếp tục theo dõi
3. và quan trọng nhất, hãy xem xét dành một chút thời gian cho mình nếu bạn đang tìm kiếm một dự án phần mềm nguồn mở có giá trị xứng đáng của bạn thời gian.

Hãy để tôi giải thích những điểm sau:

1. Tôi đã có vấn đề với: đánh dấu cao su

   • trong đánh dấu doxygen (không được hỗ trợ, nhưng phải dễ thực hiện)
   • Một số lỗi trình phân tích cú pháp (một số định nghĩa tiêu đề hàm), có vẻ như gây ra lỗi trong trình phân tích cú pháp nhân sư, nhưng không gây rắc rối nếu tôi kiểm tra chúng trong mã sphinx C++ trực tiếp. Không có ý tưởng về khó khăn của việc sửa chữa, nhưng đây là một bộ ngắt chức năng nghiêm trọng.
   • Một số sự cố với số nhận dạng bị quá tải. Dường như có một số hỗ trợ để giải quyết các hàm có cùng tên trong các lớp khác nhau và/hoặc không gian tên và/hoặc tệp kết quả doxygen xml. Nhưng hiển thị hoặc liên kết với một trong 10 nhà thầu quá tải trong một lớp đơn lẻ có vẻ như ATM không khả thi. Trong trường hợp tham chiếu/liên kết, thậm chí có một giới hạn (có thể tạm thời) song song về cấp độ nhân sư mà hít thở có thể hoặc không thể có thể hoạt động.
   • Hiện tại không có cách nào để hiển thị tất cả (hoặc tất cả được bảo vệ/riêng tư) thành viên của một lớp học. Điều này bằng cách nào đó được giới thiệu với một sửa chữa và phải thực sự tầm thường để sửa chữa.

   • Trong một ý nghĩa tổng quát hơn, hãy lưu ý rằng ATM là cầu nối đến đầu ra của Doxygen là xml. Điều đó không nên được hiểu theo cách mà nó sẽ chính xác đầu ra những gì doxygen làm, chỉ với những hạn chế ở trên. Thay vào đó, nó cung cấp cho bạn một cách chính xác, không hơn, không kém, khả năng để

     • đổ ra mọi thứ trong một miền lượng doxygen vào một trang khổng lồ
     • chương trình cụ thể chức năng, các thành viên, cấu trúc, sự đếm, typedefs, hoặc các lớp học, tuy nhiên phải được chỉ định bằng tay. Có một ngã ba trên github có thể hoặc không muốn giải quyết vấn đề khái niệm tổng thể này, nhưng không có gợi ý cho tương lai ở đó.

2. Theo tôi, một đầy đủ chức năng thở sẽ lấp đầy một khoảng trống lớn và mở ra một con đường khá mát mẻ. Vì vậy, nó là giá trị xem chỉ vì lợi ích tiềm năng .

3. Thật đáng buồn là dường như việc duy trì thông qua người sáng tạo sẽ giảm xuống nghiêm trọng trong tương lai.Vì vậy, nếu bạn đang làm việc trong một công ty và có thể thuyết phục ông chủ của bạn thở sẽ phù hợp với anh ta, hoặc có một số thời gian rảnh và tìm kiếm một dự án thực sự có giá trị, hãy xem xét để cung cấp cho nó một ngã ba!

Như một con trỏ cuối cùng, cũng lưu ý các dự án doxylink contrib cho Sphinx, mà có thể cung cấp một giải pháp trung gian: xây dựng một hướng dẫn giống như xung quanh cấu trúc mà tham chiếu (css kiểu phù hợp) tài liệu doxygen cũ (tôi nghĩ rằng bạn thậm chí có thể tiêm cùng một tiêu đề vào nhân sư và trên đầu trang của tài liệu doxygen doxygen cho look'n'feels). Bằng cách đó, dự án của bạn giữ một mối quan hệ với nhân sư, và khi thở hoàn toàn ở đó, bạn được chuẩn bị để nhảy vào. Nhưng một lần nữa: xem xét cho thấy hít thở một số tình yêu nếu nó phù hợp với chương trình nghị sự của bạn.