Cách đơn giản nhất để chạy Nhân sư trên một tệp python

Question

Chúng tôi có cấu hình Nhân sư sẽ tạo ra một loạt các tài liệu HTML cho toàn bộ codebase của chúng tôi. Đôi khi, tôi đang làm việc trên một tệp và tôi chỉ muốn xem đầu ra HTML từ tệp đó để đảm bảo rằng tôi có cú pháp đúng mà không cần chạy toàn bộ bộ.

Tôi đã tìm lệnh đơn giản nhất mà tôi có thể chạy trong thiết bị đầu cuối để chạy nhân sư trên tệp này và tôi chắc chắn thông tin ở đó nhưng tôi không thấy.

Answer 1

Nhân sư xử lý tệp reST (không phải tệp Python trực tiếp). Những tệp đó có thể chứa tham chiếu đến các mô-đun Python (khi bạn sử dụng autodoc). Kinh nghiệm của tôi là nếu chỉ có một mô-đun Python duy nhất đã được sửa đổi kể từ lần xây dựng đầu ra hoàn chỉnh cuối cùng, Nhân sư không tái sinh tất cả mọi thứ; chỉ tập tin reST mà "kéo vào" mà mô-đun Python cụ thể được xử lý. Có một thông báo nói rằng updating environment: 0 added, 1 changed, 0 removed.

Để xử lý một cách rõ ràng một file còn lại duy nhất, xác định nó như một cuộc tranh cãi để sphinx-build:

sphinx-build -b html -d _build/doctrees . _build/html your_filename.rst 

Answer 2

này được thực hiện theo hai bước:

1. Tạo tập tin đầu tiên từ các mô-đun python với sphinx- apidoc.
2. Tạo html từ tệp rst bằng công cụ xây dựng nhân sư.

Tập lệnh này thực hiện công việc. Gọi nó trong khi đứng trong cùng thư mục với mô-đun và cung cấp tên tệp của mô-đun:

#!/bin/bash 
# Generate html documentation for a single python module 

PACKAGE=${PWD##*/} 
MODULE="$1" 
MODULE_NAME=${MODULE%.py} 

mkdir -p .tmpdocs 
rm -rf .tmpdocs/* 
sphinx-apidoc \ 
    -f -e --module-first --no-toc -o .tmpdocs "$PWD" \ 
    # Exclude all directories 
    $(find "$PWD" -maxdepth 1 -mindepth 1 -type d) \ 
    # Exclude all other modules (apidoc crashes if __init__.py is excluded) 
    $(find "$PWD" -maxdepth 1 -regextype posix-egrep \ 
     ! -regex ".*/$MODULE|.*/__init__.py" -type f) 
rm .tmpdocs/$PACKAGE.rst 
# build crashes if index.rst does not exist 
touch .tmpdocs/index.rst 
sphinx-build -b html -c /path/to/your/conf.py/ \ 
    -d .tmpdocs .tmpdocs .tmpdocs .tmpdocs/*.rst 

echo "**** HTML-documentation for $MODULE is available in .tmpdocs/$PACKAGE.$MODULE_NAME.html"