Personalizza i modelli per `sphinx-apidoc`

Question

Ho recentemente provato a utilizzare sphinx-apidoc da Sphinx per aiutare a generare reStructuredText specifico della Sfinge dall'API di un progetto Python.

Tuttavia, il risultato che sto ottenendo è:

Qualcuno sa se posso personalizzare il modello sphinx-api utilizza per la sua uscita? In particolare, mi piacerebbe:

• sbarazzarsi di tutti i "moduli", "sottopackage" e "contenuti Module" voci, e
• avere i risultati dalla docstring nei miei file __init__.py comparire direttamente sotto il pacchetti, in modo che se faccio clic su un nome di pacchetto, la prima cosa che vedo è la documentazione del pacchetto. Al momento, questa documentazione è posta sotto la voce "Contenuto del modulo" un po 'strana alla fine di ogni sezione del pacchetto.

Il "moduli" e "sottopacchetti" voci sono ridondanti Credo, poiché le normali intestazioni di pacchetti/moduli è "pacchetto xxx.yyy" e "xxx.yyy.zzz modulo".

La struttura desidero per il piccolo esempio precedente è pacchetto

• orexplore.components
  • orexplore.components.mbg120 modulo
• pacchetto orexplore.simulators
  • pacchetto orexplore.simulators.test
    • modulo orexplore.simulators.test.mbg120
  • orexplore.simulators.mbg120 modulo

Dove clic sui pacchetti, la prima cosa che mi piacerebbe vedere sulla pagina sarebbe essere la documentazione del pacchetto.

O forse anche solo

• orexplore.components
  • orexplore.components.mbg120
• orexplore.simulators
  • orexplore.simulators.test
    • orexplore.simulators.test.mbg120
• orexplore.simulators.mbg120

se ci fosse un modo per distinguere visivamente pacchetti/moduli (colore? emblema?) invece del piuttosto verboso "pacchetto" e "modulo".

Answer 1

Lo script sphinx-apidoc utilizza il modulo apidoc.py. Non sono in grado di fornire istruzioni dettagliate, ma per rimuovere intestazioni o altrimenti personalizzare l'output, dovrai scrivere la tua versione di questo modulo. Non c'è altro "modello".

Si noti che se la struttura dell'API e del modulo è stabile, non è necessario eseguire sphinx-apidoc ripetutamente. È possibile post-elaborare i file rst generati a proprio piacimento una volta e posizionarli sotto il controllo della versione. Vedi anche https://stackoverflow.com/a/28481785/407651.

Answer 2

FWIW, ecco un hack completo di uno script per effettuare le modifiche desiderate, che erano anche le mie modifiche desiderate, in un file "filename.rst.new" accanto a ogni "filename.rst":

#!/usr/bin/env python 

''' 
Rearrange content in sphinx-apidoc generated .rst files. 

* Move "Module Contents" section to the top. 
* Remove headers for "Module Contents", "Submodules" and "Subpackages", 
    including their underlines and the following blank line. 
''' 


import argparse 
import glob 
import os 


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
def argument_parser(): 
    ''' 
    Define command line arguments. 
    ''' 

    parser = argparse.ArgumentParser(
     description=''' 
     Rearrange content in sphinx-apidoc generated .rst files. 
     ''' 
     ) 

    parser.add_argument(
     '-v', '--verbose', 
     dest='verbose', 
     default=False, 
     action='store_true', 
     help=""" 
      show more output. 
      """ 
     ) 

    parser.add_argument(
     'input_file', 
     metavar="INPUT_FILE", 
     nargs='+', 
     help=""" 
      file. 
      """ 
     ) 

    return parser 


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
def main(): 
    ''' 
    Main program entry point. 
    ''' 

    global args 
    parser = argument_parser() 
    args = parser.parse_args() 

    filenames = [glob.glob(x) for x in args.input_file] 
    if len(filenames) > 0: 
     filenames = reduce(lambda x, y: x + y, filenames) 

    for filename in set(filenames): 

     # line_num was going to be for some consistency checks, never 
     # implemented but left in place. 
     found = { 
      'Subpackages': {'contents': False, 'line_num': None}, 
      'Submodules': {'contents': False, 'line_num': None}, 
      'Module contents': {'contents': True, 'line_num': None}, 
      } 

     in_module_contents = False 
     line_num = 0 
     reordered = [] 
     module_contents = [] 

     new_filename = '.'.join([filename, 'new']) 

     with open(filename, 'r') as fptr: 

      for line in fptr: 
       line = line.rstrip() 
       discard = False 

       line_num += 1 

       if (
         in_module_contents 
         and len(line) > 0 
         and line[0] not in ['.', '-', ' '] 
         ): # pylint: disable=bad-continuation 
        in_module_contents = False 

       for sought in found: 

        if line.find(sought) == 0: 

         found[sought]['line_num'] = line_num 
         if found[sought]['contents']: 
          in_module_contents = True 

         discard = True 
         # discard the underlines and a blank line too 
         _ = fptr.next() 
         _ = fptr.next() 

       if in_module_contents and not discard: 
        module_contents.append(line) 

       elif not discard: 
        reordered.append(line) 

       # print '{:<6}|{}'.format(len(line), line) 

     with open(new_filename, 'w') as fptr: 
      fptr.write('\n'.join(reordered[:3])) 
      fptr.write('\n') 
      if module_contents: 
       fptr.write('\n'.join(module_contents)) 
       fptr.write('\n') 
       if len(module_contents[-1]) > 0: 
        fptr.write('\n') 
      if reordered[3:]: 
       fptr.write('\n'.join(reordered[3:])) 
       fptr.write('\n') 


if __name__ == "__main__": 
    main() 

Answer 3

Ho implementato better-apidoc, una versione con patch dello script sphinx-apidoc che aggiunge il supporto completo per i modelli.

aggiunge un'opzione -t/--template, che permette di passare una directory modello che deve contenere i file di modello package.rst e module.rst. Vedi package.rst e module.rst per un esempio. Questi rendono ad es. http://qnet.readthedocs.io/en/latest/API/qnet.algebra.operator_algebra.html.