Sphinx

Quando creato per la prima volta, il suo scopo principale era quello di fungere da generatore di documentazione per Python s 'proprio codice.
Da allora, il progetto ha raggiunto lo status di culto nel mondo dello sviluppo, essendo una delle influenze più riferimento a generatori di documentazione più automatiche intorno, indipendentemente dalla lingua.
Oggi, oltre solo Python, Sphinx può essere utilizzato anche con C e C ++ codice pure.

Cosa c'è di nuovo in questa versione:

• Aggiungi direttive convenienza e ruoli per il C ++ dominio: direttiva `` cpp: var`` come alias per `` cpp: member``, ruolo ``: cpp: var`` come alias per ``: cpp: membro ``, e il ruolo `any` per riferimento incrociato a qualsiasi ++ declaraction C.
• Il: confval: `valore config source_suffix` ora può essere un elenco di più suffissi
.
• Aggiungi la possibilità di specificare parser di origine per il suffisso di origine con l': confval:. `Valore config source_parsers`
• Un nuovo costruttore, AppleHelpBuilder, è stato aggiunto che costruisce di Apple Aiuto libri.

Cosa c'è di nuovo nella versione 1.2.3 / 1.3b3:

• aggiunta `` sphinx.version_info`` tuple per la verifica programmatica della versione Sfinge.

Cosa c'è di nuovo nella versione 1.1.3:

• Risolto crash con alcune impostazioni di: confval:. `Modindex_common_prefix`
• fissi trattamento dei `` -D`` e `` opzioni -A`` su Python 3.
• Riconosciuto e mettere in guardia circa toctrees circolari, invece di correre in errori di ricorsione.
• Ripristina compatibilità con docutils tronco.
• HtmlHelp fisse collegamenti voce di indice di nuovo.
• inheritance_diagram fisso sollevando errori attributo builtin.
• Corretti i crash quando mettono commenti o termini solitari in un glossario.
• Guida HTML fisso mappatura del linguaggio / codifica per tutti Sfinge lingue supportate.

Cosa c'è di nuovo nella versione 1.1:

• Caratteristiche aggiunto:
• Supporto 3.x. Aggiunto Python.
• Nuovi costruttori e sottosistema.
• modifiche incompatibili:
• Il: primo: dir: `py: direttiva module` non emette il suo valore opzione` `platform`` più. (Era l'unica cosa che la direttiva ha fatto di uscita, e quindi abbastanza incoerente.)
• Supporto Rimosso per le versioni vecchie di dipendenza.
• Nuovi locali:
• Aggiunta localizzazione svedese.
• Aggiunta locale iraniano.
• Aggiunta locale lettone.
• Aggiunta locale nepalese.
• Inserito locale coreano.
• Aggiunta localizzazione Estone.

Cosa c'è di nuovo nella versione 1.0.8:

• traceback correzione per AttributeErrors nella produzione autosummary.
• Fissare il `` abbr`` ruolo quando la sigla è a capo di esso.
• Fissare i collegamenti ai risultati con i tipi di oggetti personalizzati ricerca.
• i numeri di riga Fix riportati in avvertimenti circa i riferimenti non definiti.
• Fix C ++ definizioni matrice e argomenti di modello che non sono di tipo nomi.
• Consenti note in intestazioni di sezione in uscita LaTeX.
• Consenti parole chiave per essere collegati tramite intersphinx.
• Consenti caratteri Unicode nella lista produzione nomi dei token.
• Aggiungi visitatori fittizi per i nodi graphviz per il testo e l'uomo.
• Fix immagine duplicazione di file bug.
• Fix analisi di firme multiple in C ++ dominio.
• Ignora i file di lock Emacs quando alla ricerca di file di origine.
• Consenti estensione .pyw per i moduli importabili in autodoc.
• Usa `` $ (make) `` in quickstart generato Makefile.
• Fai sidebar larghezza casella di ricerca coerente nei browser.
• spaziatura Fix di figure centrate in output HTML.
• sicura codificare i messaggi SphinxError durante la stampa li a sys.stderr.
• errore uscita Fix LaTeX con un documento senza le sezioni, ma una destinazione del collegamento.
• correttamente trattare incorporate descrittori Metodo metodi autodoc.
• Arresto monkeypatching modulo textwrap Python.
• ViewCode ora funziona correttamente con i file di origine che hanno codifica non ASCII.
• Rispettare l'opzione bandierina `` noindex`` in py:. Direttive modulo
• IndexErrors Fix quando comprese inesistente linee con: primo: dir.: `Literalinclude`

Stringhe
• Rispetto funzione custom / parametro separatore metodo.
• incompatibilità Fix JS con jQuery & gt;. = 1.5
• Fissare doppia codifica fatto durante la scrittura di HTML .hhk file.
• Non applicare Smartypants in blocchi-letterali analizzati.
• C ++ dominio ora supporta le definizioni di matrice.

Cosa c'è di nuovo nella versione 1.0.6:

• Fix traceback nel dominio Python per target di riferimento incrociato vuote.
• Risolvere problemi di visualizzazione blocco letterali su browser Chrome.
• Supporto ordinamento una gamma limitata di caratteri accentati nell'indice generale e il glossario.
• Prova decodifica `` `` -D`` e argomenti della riga di comando -A`` con codifica preferita dal locale.
• Rispettare: confval:. `Locale_dirs` quando si cerca il file di traduzioni JS
• Aggiungi codice speciale per un miglior supporto di documenti giapponesi nel costruttore LaTeX.
• Regressione di # 77: Se vi è un solo parametro dato con ``: param:. `` Markup, il punto elenco è ormai soppressa nuovamente
• Fissare mancante interruzioni di paragrafo in uscita LaTeX in certe situazioni.
• Emit l'evento `` autodoc-processo-docstring`` anche per gli oggetti senza una docstring in modo che possa aggiungere contenuti.
• Nel generatore LaTeX, non solo blocchi letterali richiedono un trattamento tabella diversa, ma anche parecchi altri elementi di blocco della lista-like.
• traceback Fissare nell'estensione ViewCode per oggetti Python che non hanno una firma valida.
• Fix strani reportings di numeri di linea per gli avvisi generati da docstrings AutoDoc-incluso, a causa di un comportamento diverso a seconda della versione docutils.
• Diverse correzioni al dominio C ++.

Cosa c'è di nuovo nella versione 1.0.5:

• Aggiungi stili CSS richieste dalla docutils 0,7 per le immagini allineate e figure.
• Nella Makefile generato dall'uscita LaTeX, non eliminare i file PDF su pulito; potrebbero essere necessarie le immagini.
• uscita Fix LaTeX generato per i blocchi di linea.
• Consenti `` .pyw`` come estensione file sorgente.

Cosa c'è di nuovo nella versione 1.0.4:

• Apri inventari intersphinx in modalità binaria su Windows, a partire dalla versione 2 contiene dati zlib-compressa.
• Consenti dando URI non locali per file JavaScript, ad esempio, nell'estensione jsMath.
• Fix traceback quando `` intersphinx_mapping`` è vuoto.

Cosa c'è di nuovo nella versione 1.0.3:

• Fix interno contro distinzione link esterno per i link provenienti da un docutils tavolo-di-contenuti.
• Fissare l'opzione `` maxdepth`` per il `` toctree () `` modello richiamabile quando viene utilizzato con `` crollo = True``.
• schianto Fix analisi liste di argomenti Python contenenti parentesi nelle stringhe letterali.
• Fix regressione quando si costruisce documenti LaTeX con figure che non hanno didascalie.
• Fix diagrammi di eredità per le classi che non sono serializzabili.
• Introdurre il colore di sfondo a parte per il pulsante di barra laterale crollo, rendendo più facile da vedere.
• Fissare piccoli bug di layout in diversi temi incorporati.

Cosa c'è di nuovo nella versione 1.0.2:

• Fissare rimandi agli oggetti di tipi aggiunti dal: func:. `~ Funzione API .Sphinx.add_object_type`
• gestione Fix di tipi di campo doc per diversi tipi direttiva.
• Consenti rottura lunghe firme, continuando con a capo senza gioco escape.
• Fix styling indesiderata di C riferimenti a dominio (a causa di uno scontro namespace con gli stili Pygments).
• Consenti riferimenti a persone politicamente esposte e RFC con ancore espliciti.
• riferimenti Fix LaTeX nei confronti di personalità.
• Quando si effettua una ricerca non esatta, partita solo il tipo data dell'oggetto.
• Applica ricerca non esatta per target di riferimento di Python con `` .name`` per i moduli anche.
• schianto Fix quando la duplicazione di un parametro in un elenco di informazioni di campo.
• Fissare l'impostazione del ruolo predefinito di quello fornito dalla `` estensione oldcmarkup``.
• arresto Fix quando è installato JSON-py, che fornisce un modulo `` json`` ma è incompatibile simplejson.
• gestione Fix del target di denominazione in intersphinx.
• rimozione Fix di ``! `` Per tutti i ruoli di riferimenti incrociati.

Cosa c'è di nuovo nella versione 1.0.1:

• Fissare nomi di destinazione creati per oggetti di dominio riposo; non sono nello stesso namespace.
• Aggiungi lingua bengalese.
• Correggere un bug nel parsing nomi degli oggetti JavaScript.
• Fix edificio con SingleHTMLBuilder quando non c'è toctree.
• nomi visualizzati Fix per gli oggetti legati al da intersphinx con obiettivi espliciti.
• Fissare la costruzione con il costruttore JSON.
• ipertestuali, fissare nella descrizione degli oggetti per LaTeX.

Cosa c'è di nuovo nella versione 1.0:

• Generale:
• Aggiunta la modalità "nitpicky" che emette avvisi per tutti i riferimenti mancanti. Si attiva l'opzione:: `-n` opzione della riga di comando o il: confval:.` Valore config nitpicky`
• aggiunta `` obiettivo latexpdf`` in quickstart Makefile.
• Markup:
• Il: primo: ruolo: `menuselection` e: prima: ruolo:. 'Ruoli guilabel` ora supportano acceleratori ampersand
• Nuova sintassi campo doc più compatto è ormai riconosciuto: ``: Nome Tipo param:. Description``
• aggiunta `` opzione scheda-width`` a: primo: dir. `Direttiva literalinclude`
• aggiunta `` opzione titlesonly`` a: primo: dir. `Direttiva toctree`
• Aggiunta la `` prepend`` e `` opzioni append`` al: primo: dir. `Direttiva literalinclude`
• Tutti DocInfo metadati è ora messo in metadati del documento, non solo l'autore.
• Il: primo: ruolo: `ruolo ref` ora può fare riferimento anche tavoli da titolo
.
• Il: primo: dir. `Direttiva include` ora supporta percorsi assoluti, che sono interpretati come relativo alla directory di origine
• Nel dominio Python, riferimenti, come ``: func:. `.name``` Ora cercare nomi corrispondenti con qualsiasi prefisso se non viene trovata alcuna corrispondenza diretta
• Configurazione:
• Aggiunto: confval:. Valore `rst_prolog` config
• Aggiunto: confval:. `Valore html_secnumber_suffix` config per controllare la sezione formato di numerazione
• Aggiunto: confval:. `Valore html_compact_lists` config per controllare le liste compatte docutils 'dispongono
• Il: confval: `valore config html_sidebars` ora può contenere modelli come le chiavi, ed i valori possono essere liste che selezionano in modo esplicito che i modelli della barra laterale, si trasformano. Ciò significa che il contenuto della sidebar incorporate possono essere inclusi solo in modo selettivo.
• : confval:. 'Html_static_path` possono ora contenere voci del file singoli
• Il nuovo valore di configurazione universale: confval: `exclude_patterns` rende il vecchio: confval:` unused_docs`,: confval: `exclude_trees` e: confval:.` Exclude_dirnames` obsoleto
• Aggiunto: confval:. Valore `html_output_encoding` config
• Inserito il: confval: `valore config latex_docclass` e ha reso l'opzione documentclass" twoside "override da" oneside "
.
• Inserito il: confval:. `Valore config trim_doctest_flags`, il che è vero per default
• Aggiunto: confval:. Valore `html_show_copyright` config
• Aggiunto: confval: `latex_show_pagerefs` e: confval:. 'I valori di configurazione latex_show_urls`
• Il comportamento di: confval: `html_file_suffix` leggermente cambiata: la stringa vuota significa che ora" nessun suffisso "invece di" suffisso predefinito ", l'uso` `None`` per" suffisso predefinito "
.
• Nuovi costruttori:
• Aggiunto un costruttore per il formato Epub.
• Aggiunto un costruttore per le pagine di manuale.
• Aggiunto un costruttore di HTML a file singolo.
• output HTML:

Ruoli
• Inline ora ottenere una classe CSS con il loro nome, che permette stili di personalizzare la loro apparenza. Ruoli specifici di dominio ottengono due classi, `` domain`` e `` dominio rolename``.
• Riferimenti ora ottenere la classe `` internal`` se sono interni a tutto il progetto, in contrasto interno alla pagina corrente.
• I riferimenti esterni può essere uno stile diverso con la nuova opzione tema `` externalrefs`` per il tema di default.
• In tema di default, la barra laterale può sperimentalmente ora fatto pieghevole con la nuova opzione tema `` collapsiblesidebar``.
• Toctrees ora sono avvolti in un `` div`` tag con classe `` toctree-wrapper`` in output HTML.
• I: i dati:. 'Toctree` richiamabile nei template ora ha un `` maxdepth`` argomento chiave per controllare la profondità dell'albero generato
• I: i dati:. 'Toctree` richiamabile in modelli ora accetta un `` argomento parola titles_only``
• aggiunta `` blocco htmltitle`` in modello di layout.
• Nella ricerca di JavaScript, consente la ricerca di nomi di oggetti, tra cui il nome del modulo, come `` sys.argv``.
• Aggiunto nuovo tema `` haiku``, ispirato al manuale d'uso Haiku OS.
• Aggiunta nuovo tema `` nature``.
• Aggiunto nuovo tema `` agogo``, creato da Andi Albrecht.
• Aggiunto nuovo tema `` scrolls``, creato da Armin Ronacher.
• Aggiunta una opzione tema `` visitedlinkcolor`` al tema di default.
• migliorata la reattività della pagina ricerca caricando thesearch indice in modo asincrono.
• API Estensione:
• Aggiunto: evento:. `Html-collect-pages`
• Aggiunto: confval: `valore config needs_sphinx` e: meth:.` ~ Metodo sphinx.application.Sphinx.require_sphinx` API di applicazione
• Aggiunto: meth:. Metodo `~ sphinx.application.Sphinx.add_stylesheet` API applicazione
• Estensioni:
• Inserito il: mod: `~ estensione sphinx.ext.viewcode`
.
• Inserito il: mod: `~ estensione sphinx.ext.extlinks`
.
• Aggiunto il supporto per fonte ordinamento dei membri in autodoc, con `` autodoc_member_order = 'bysource'``.
• Aggiunto: confval:. `Autodoc_default_flags` valore config, che può essere usato per selezionare le bandiere di default per tutte le direttive AutoDoc
• Aggiunto un modo per intersphinx fare riferimento alle etichette con nome in altri progetti, e per specificare il progetto che si desidera collegare.
• Autodoc può ora documentare esempio attributi assegnati in `` metodi __init__``.
• Molti miglioramenti e correzioni al: mod. `~ Estensione sphinx.ext.autosummary`, grazie a Pauli Virtanen
• Il: mod: `~ estensione sphinx.ext.graphviz` possono SVG ora in uscita invece di immagini PNG, controllato dal confval:.` Valore config graphviz_output_format`
• aggiunta `` opzione alt`` a: primo: dir. `Direttive estensione graphviz`
• aggiunta `` argomento exclude`` a: func:. `.autodoc.between`
• Traduzioni:
• Aggiunta la traduzione in croato, grazie a Bojan Mihelač.
• aggiunta traduzione in turco, grazie a Firat Ozgul.
• traduzione Aggiunto catalana, grazie a Pau Fernandez.
• Aggiunta la traduzione in cinese semplificato.
• Aggiunta la traduzione in danese, grazie al Hjorth Larsen.
• Aggiunta la traduzione in lituano, grazie a Dalius Dobravolskas.

Cosa c'è di nuovo nella versione 1.0b1:

• è stato aggiunto il supporto per i domini. Un dominio è un insieme di direttive e ruoli che tutti descrivono oggetti appartenenti insieme, ad esempio, elementi di un linguaggio di programmazione. Sono forniti Alcuni domini builtin: - Python - C - C ++ - JavaScript - reStructuredText
• Il vecchio markup per la definizione e il collegamento alle direttive C non funziona più senza attivare il `` estensione oldcmarkup``.
• Supporto Rimosso per le versioni vecchie di dipendenza.
• elementi deprecati rimossi.

Cosa c'è di nuovo nella versione 0.6.5:

• Nella autodoc, fissare l'omissione di alcuni membri del modulo esplicitamente documentati utilizzando i commenti di documentazione.
• Fix ritaglio di barra laterale barra di scorrimento con `` opzione stickysidebar`` del tema di default.
• generare sempre nuove righe UNIX nel Makefile quickstart.
• Fix esecuzione con `` -C`` sotto Windows.
• Nella autodoc, permettono la personalizzazione della firma di un oggetto in cui il meccanismo incorporato fallisce.
• uscita Fix per elenchi numerati con valori iniziali in LaTeX.
• Fare la `` start-after`` e `` opzioni end-before`` all'opera direttiva `` literalinclude`` correttamente se non utilizzati insieme.
• generazione collegamento Fix nel generatore LaTeX.

Cosa c'è di nuovo nella versione 0.6.4:

• Migliorata la gestione delle stringhe non Unicode nella configurazione.
• OSErrors di cattura che si verificano quando si chiama graphviz con argomenti che non capisce.
• Ripristina compatibilità con Pygments & gt;. = 1.2
• Fix fuga di obiettivi hyperref in uscita LaTeX.
• Link Fix generati dal ``: doc: ``. Ruolo per l'uscita LaTeX
• Raccogli todo nodi dopo l'intero documento è stato letto; questo permette di collocare i riferimenti di sostituzione in todo oggetti.
• Non ignorare un `` valore config today`` esplicito in una build LaTeX.
• Il `` testo alt`` di diagrammi di eredità è ora molto più pulito.
• Ignora le immagini in titoli di sezione durante la generazione di link didascalie.
• Messaggi Supporto eccezione nel `` blocchi testoutput`` del `estensione` doctest``.
• blocchi di linea sono arredate in modo corretto output HTML.
• Fatto di nuovo il lavoro valore di configurazione `` locale_dirs``.
• `` valori html_context`` riportati sulla linea di comando tramite `` -A`` non dovrebbero ignorare gli altri valori indicati in conf.py.
• Risoluzione di un problema che impedisce ricostruzioni incrementali per la `` costruttore dirhtml``.
• Fissare la storpiatura di citazioni in alcuni blocchi letterali.
• percorso Correggi per l'indice di ricerca per la `` costruttore dirhtml``.
• Risoluzione problema di compatibilità Jython: rendere la dipendenza dal modulo `` parser`` opzionale
.
• Nella autodoc, catturare tutti gli errori che si verificano sul modulo di importazione, non solo `` ImportError``.
• Fissare il trattamento dei non dati, ma non il metodo descrittori autodoc.
• Durante la copia di file volte, ignorare OSErrors sollevate da `` os.utime () ``.

Requisiti

• Pygments 1.2 o superiore
• Jinja 2.3 o superiore
• Docutils 0/7 o superiore