اجعل sphinx توليد وثائق فئة RST من Pydoc

Question

أقوم حاليًا بترحيل جميع الوثائق الموجودة (غير مكتملة) إلى أبو الهول.

المشكلة هي أن الوثائق تستخدم Python docstrings (تمت كتابة الوحدة النمطية في C ، ولكن من المحتمل أن لا يهم) ويجب تحويل وثائق الفصل إلى نموذج قابل للاستخدام لـ sphinx.

هنالك sphinx.ext.autodoc, ، لكنه يضع المستندات الحالية تلقائيًا على المستند. أريد إنشاء ملف مصدر في (RST) استنادًا إلى docstrings الحالية ، والتي يمكنني بعد ذلك تحريرها وتحسينها يدويًا.

كيف يمكنك تحويل docstrings إلى RST لـ sphinx؟

Answer 1

تقوم AutoDOC بتوليد RST فقط لا توجد طريقة رسمية لإخراجها منه. كان أسهل اختراق للحصول عليه من خلال التغيير sphinx.ext.autodoc.Documenter.add_line طريقة لإبعاد لي الخط الذي يحصل عليه.

بما أن كل ما أريده هو ترحيل لمرة واحدة ، فإن الإخراج إلى stdout جيد بما يكفي بالنسبة لي:

def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    print self.indent + line
    self.directive.result.append(self.indent + line, source, *lineno)

الآن ، تم إنشاء مطبوعات AutoDoc على stdout أثناء التشغيل ويمكنك ببساطة إعادة توجيهها أو نسخها في مكان آخر.

Answer 2

قرد تصحيح Autodoc بحيث يعمل دون الحاجة إلى تحرير أي شيء:

import sphinx.ext.autodoc
rst = []
def add_line(self, line, source, *lineno):
    """Append one line of generated reST to the output."""
    rst.append(line)
    self.directive.result.append(self.indent + line, source, *lineno)
sphinx.ext.autodoc.Documenter.add_line = add_line
try:
    sphinx.main(['sphinx-build', '-b', 'html', '-d', '_build/doctrees', '.', '_build/html'])
except SystemExit:
    with file('doc.rst', 'w') as f:
        for line in rst:
            print >>f, line

Answer 3

بقدر ما أعرف أنه لا توجد أدوات تلقائية للقيام بذلك. وبالتالي ، فإن نهائي هو كتابة نص صغير يقرأ الوحدات ذات الصلة (استنادًا إلى العضلة العضلية.