Come pre-processare i file sorgente mentre una Sfinge è in esecuzione?

Question

Ho creato una documentazione Sphinx per il mio progetto e vorrei estrarre le stringhe doc per i file sorgente e incorporarle nella documentazione finale. Sfortunatamente, la lingua del file sorgente (VHDL) non è supportata da Sphinx. Sembra che non ci sia alcun dominio Sphinx per VHDL.

Quindi le mie idee è la seguente:

• Hook nella Sfinge eseguire ed eseguire codice Python prima Sfinge
• I codici Python estratti i blocchi di testo da ogni file sorgente (il più in alto multi-linea blocco di commenti) e assembla un file reST per file sorgente, costituito da questo blocco di commenti e qualche altro markup di ripristino.
• Tutti i file di origine sono elencati in un index.rst, per generare la direttiva .. toctree:: appropriata.
• L'estrazione e la trasformazione del testo vengono eseguite in modo ricorsivo per directory del codice sorgente.

Quindi la domanda principale è: Come collegarsi a Spinx?

Oppure devo solo importare ed eseguire la mia configurazione in 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. 
# .... 

non posso modificare i file di processo di compilazione: Makefile e make.bat, perché il vero processo di compilazione viene eseguito su ReadTheDocs.org. RTD esegue solo conf.py.

Answer 1

Come notato nei miei commenti precedenti e nella risposta di mertyildiran, il modo ufficiale di aggancio nella Sfinge per una lingua è create an extension per implementare un nuovo dominio per VHDL.

Questo è già stato fatto per molte altre lingue, ad es. Erlang, PHP, CoffeeScript e API - ad es. HTTP REST - solo per citarne alcuni da sphinx-contrib. Tuttavia, ci vorrà un sacco di tempo, che non hai ... Sei quindi lasciato con l'opzione di fare un rapido parsing te stesso e poi collegarlo alla tua sfinge in qualche modo.

Dal momento che si sta bypassando i ganci ufficiali, questa domanda diventa "come lo faccio eseguire il mio codice all'interno di una Sfinge costruire?" Per cui, ti consiglio di seguire semplicemente la guida per un'estensione locale, ad esempio inserirla in una directory separata, aggiungerla al percorso, quindi importarla e richiamarla. Come osservato nel docs:

Il file di configurazione viene eseguito come codice Python al momento della compilazione (mediante execfile(), e con la directory corrente impostata alla sua directory che contiene), e quindi in grado di eseguire codice arbitrario complesso. Sfinge legge quindi nomi semplici dal namespace del file come sua configurazione.

Come una finale, però, questo apre le opzioni per utilizzare i pacchetti 3a parte come pyVhdl2Sch (con un cenno di nuovo per la risposta di mertyildiran) per creare un po 'schematico e poi magari scrivere i rst file statici intorno ad esso per spiegare lo schema .

Answer 2

Stai provando a usare un martello per rompere un dado.

Sfinge è stato originariamente creato per la nuova documentazione Python, e ha eccellenti strutture per la documentazione dei progetti di Python, ma C/C++ è già supportato pure, e si prevede di aggiungere speciali il supporto per altre lingue pure. http://www.sphinx-doc.org/en/stable/

VHDL non è attualmente una lingua supportata dalla Sfinge e perché VHDL è un linguaggio di descrizione hardware sua priorità per diventare una lingua supportata deve essere bassa. Hai due opzioni e prima è anche il mio suggerimento per voi:

1) Utilizzare un determinato strumento generatore di documentazione VHDL invece di Sfinge

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

Un programma di utilità di documentazione VHDL scritto in Perl, basato su Doxygen.

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

pyVhdl2Sch è uno strumento generatore di documentazione. Prende i file VHDL (.vhd) come voce e genera uno schema pdf/svg/ps/png per ogni file di input. Scritto in puro Python, più amichevole per la comunità, più aggiornato.

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

edizione High-end di Sigasi Studio, che è un prodotto commerciale.

2) Contribuire al progetto Sfinge e aggiungere dominio VHDL

Segui Sphinx Developer's Guide e acquisire familiarità con la struttura del progetto. Aggiungere eventualmente vhdl.py a questa directory del progetto: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains

Questa seconda opzione non può essere spiegata con una risposta StackOverflow. Spetta a te se vuoi aggiungere più funzionalità a un progetto open source come Sphinx.