Làm thế nào để xử lý trước các tệp nguồn trong khi Sphinx chạy?

Question

Tôi đã thiết lập tài liệu Sphinx cho dự án của mình và muốn trích xuất chuỗi tài liệu cho các tệp nguồn và nhúng chúng vào tài liệu cuối cùng. Thật không may, ngôn ngữ của tệp nguồn (VHDL) không được Sphinx hỗ trợ. Dường như không có miền Sphinx cho VHDL.

Vì vậy, ý tưởng của tôi là như sau:

• Hook vào Sphinx chạy và thực hiện một số mã Python trước Sphinx
• Các mã Python chiết xuất khối văn bản từ mỗi tập tin nguồn (the-nhất trên nhiều dòng khối nhận xét) và tập hợp một tệp reST cho mỗi tệp nguồn, bao gồm khối nhận xét này và một số đánh dấu lại khác.
• Tất cả các tệp nguồn được liệt kê trong một index.rst, để tạo chỉ thị .. toctree:: thích hợp.
• Việc trích xuất và chuyển đổi văn bản được thực hiện đệ quy cho mỗi thư mục mã nguồn.

Vì vậy, câu hỏi chính là: Cách móc vào Spinx?

Hoặc tôi chỉ nên nhập và chạy cấu hình của riêng mình trong conf.py?

#!/usr/bin/env python3 
# -*- coding: utf-8 -*- 
# 
from my_preprocessor import my_proc 
proc = my_proc() 
proc.run() 
# 
# Test documentation build configuration file, created by 
# sphinx-quickstart on Tue May 24 11:28:20 2016. 
# .... 

tôi không thể sửa đổi các tập tin quá trình xây dựng: Makefile và make.bat, bởi vì quá trình xây dựng thực chạy trên ReadTheDocs.org. RTD chỉ thực hiện conf.py.

Answer 1

Như đã lưu ý trong các nhận xét trước đây và câu trả lời của mertyildiran, cách chính thức để ghép vào Sphinx cho một ngôn ngữ sẽ là create an extension để triển khai miền mới cho VHDL.

Điều này đã được thực hiện cho nhiều ngôn ngữ khác - ví dụ: Erlang, PHP, CoffeeScript - và API - ví dụ: HTTP REST - chỉ cần đặt tên một vài từ sphinx-contrib. Tuy nhiên, điều đó sẽ mất rất nhiều thời gian, mà bạn không có ... Bạn do đó còn lại với một tùy chọn để làm một số phân tích cú pháp nhanh chóng chính mình và sau đó hooking đó vào xây dựng Sphinx của bạn bằng cách nào đó.

Vì bạn đang bỏ qua các móc chính thức, câu hỏi này sẽ trở thành "làm cách nào để chạy mã của riêng tôi trong một bản dựng Sphinx?" Trong đó, tôi khuyên bạn chỉ cần làm theo hướng dẫn cho tiện ích mở rộng địa phương - tức là đặt nó vào một thư mục riêng biệt, thêm nó vào đường dẫn của bạn, sau đó nhập và gọi nó. Như đã lưu ý trong số docs:

Tệp cấu hình được thực thi dưới dạng mã Python ở thời gian xây dựng (sử dụng execfile() và do đó có thể thực thi mã phức tạp tùy ý. Nhân sư sau đó đọc tên đơn giản từ không gian tên của tệp dưới dạng cấu hình của nó.

Là một thức tuy nhiên, điều này mở ra các tùy chọn để sử dụng các gói bên thứ 3 như pyVhdl2Sch (với một cái gật đầu một lần nữa để trả lời mertyildiran của) để tạo ra một số sơ đồ và sau đó có thể viết tĩnh rst tập tin của bạn xung quanh nó để giải thích sơ đồ .

Answer 2

Bạn đang cố gắng sử dụng búa tạ để bẻ khóa đai ốc.

Sphinx ban đầu được tạo ra cho các tài liệu Python mới, và nó có cơ sở vật chất tuyệt vời cho tài liệu của dự án Python, nhưng C/C++ đã được hỗ trợ là tốt, và nó được dự tính bổ sung hỗ trợ đặc biệt cho các ngôn ngữ khác nữa. http://www.sphinx-doc.org/en/stable/

VHDL hiện không phải là một ngôn ngữ được hỗ trợ bởi Sphinx và vì VHDL là một ngôn ngữ mô tả phần cứng ưu tiên của mình để trở thành một ngôn ngữ được hỗ trợ phải là thấp. Bạn có hai lựa chọn và một đầu tiên cũng là đề nghị của tôi cho bạn:

1) Sử dụng cụ thể một công cụ tạo tài liệu VHDL thay vì Sphinx

VHDocL - http://www.volkerschatz.com/hardware/vhdocl.html

Một tiện ích tài liệu VHDL được viết bằng Perl, dựa trên Doxygen.

pyVhdl2Sch-http://laurentcabaret.github.io/pyVhdl2Sch/

pyVhdl2Sch là một công cụ tạo tài liệu. Nó lấy các tệp VHDL (.vhd) làm mục nhập và tạo ra một sơ đồ pdf/svg/ps/png cho mỗi tệp đầu vào. Được viết bằng Python thuần túy, thân thiện với cộng đồng hơn, được cập nhật nhiều hơn.

Sigasi Studio XL Doc-http://www.sigasi.com/products/

High kết thúc phiên bản của Sigasi Studio mà là một sản phẩm thương mại.

2) Đóng góp cho dự án Sphinx và thêm VHDL miền

Thực hiện theo Sphinx Developer's Guide và trở nên quen thuộc với cấu trúc của dự án. Cuối cùng, hãy thêm vhdl.py vào thư mục dự án này: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains

Tùy chọn thứ hai này không thể giải thích được bằng câu trả lời StackOverflow. Đó là vào bạn nếu bạn muốn thêm nhiều chức năng hơn cho một dự án nguồn mở như Sphinx.