Sphinx autodoc'tan yeniden yapılandırıldı

Question

CPython belgeleri için autodoc kullanmaz - elle yazılmış nesneyi kullanırız.

PEP 3144 (ipadresi modülü) için, ilk başvuru belgelerini oluşturmak için sphinx-apidoc kullanmak istiyorum. Ben iki taramalı işlemi çalıştırmak istiyorum gelir:

1. Kullanım sfenks-apidoc AutoDoc bağlıdır modül için bir Sfenks projesini yayacak şekilde

2. Run yeni reStructuredText kaynak dosyalarını oluşturan bir sfenks oluşturucu tüm AutoDoc direktifleri aynı çıktıyı

ilk adım basittir, ama nasıl ikinci adımı yapmak için hiçbir fikrim yok ve hatta iyi düşünemiyorum üreten inline reStructuredText içerik ve biçimlendirme yerini ile f arama yolları veya bu satırlardaki mevcut projeler.

Answer 1

Aynı sorunu yaşadım ve bir keresinde dokümanlar ürettim, Sphinx'in yamalarına oldukça çirkin bir çözüm kullandım, bkz. Make Sphinx generate RST class documentation from pydoc.

Answer 2

değil tam cevap, az ya da çok bir başlangıç ​​noktasıdır:

autodoc piton direktiflerine oto direktiflerini çevirir. Bu nedenle, çevrilmiş python yönergelerini almak için autodoc olaylarını kullanabilirsiniz. Örneğin

Eğer mymodule.py aşağıdaki varsa:

NAMES = [] 
DIRECTIVES = {} 

def get_rst(app, what, name, obj, options, signature, 
      return_annotation): 
    doc_indent = ' ' 
    directive_indent = '' 
    if what in ['method', 'attribute']: 
     doc_indent += ' ' 
     directive_indent += ' ' 
    directive = '%s.. py:%s:: %s' % (directive_indent, what, name) 
    if signature: # modules, attributes, ... don't have a signature 
     directive += signature 
    NAMES.append(name) 
    rst = directive + '\n\n' + doc_indent + obj.__doc__ + '\n' 
    DIRECTIVES[name] = rst 

def write_new_docs(app, exception): 
    txt = ['My module documentation'] 
    txt.append('-----------------------\n') 
    for name in NAMES: 
     txt.append(DIRECTIVES[name]) 
    print '\n'.join(txt) 
    with open('../doc_new/generated.rst', 'w') as outfile: 
     outfile.write('\n'.join(txt)) 

def setup(app): 
    app.connect('autodoc-process-signature', get_rst) 
    app.connect('build-finished', write_new_docs) 

size verecektir:

#!/usr/bin/env python 
# -*- coding: utf-8 -*- 

""" 
This is my module. 
""" 

def my_test_func(a, b=1): 
    """This is my test function""" 
    return a + b 

class MyClass(object): 
    """This is my class""" 

    def __init__(x, y='test'): 
     """The init of my class""" 
     self.x = float(x) 
     self.y = y 

    def my_method(self, z): 
     """This is my method. 

     :param z: a number 
     :type z: float, int 
     :returns: the sum of self.x and z 
     :rtype: float 
     """ 
     return self.x + z 

sphinx-apidoc

mymodule Module 
=============== 

.. automodule:: mymodule 
    :members: 
    :undoc-members: 
    :show-inheritance: 

aşağıdaki uzantıyı (veya conf.py eklenmesini) yaratacak :

Ancak

My module documentation 
----------------------- 

.. py:module:: mymodule 


This is my module. 


.. py:class:: mymodule.MyClass(x, y='test') 

    This is my class 

    .. py:method:: mymodule.MyClass.my_method(z) 

     This is my method. 

     :param z: a number 
     :type z: float, int 
     :returns: the sum of self.x and z 
     :rtype: float 


.. py:function:: mymodule.my_test_func(a, b=1) 

    This is my test function 

hiçbir olay, çeviri tamamlandığında, AutoDoc tarafından yapılan Yani ileri işleme burada Docstringler adapte edilmelidir yayar.