Usa Sphinx per creare documentazione in più formati su CentOS 7

• Prerequisiti
• Passaggio 1: aggiornare il sistema
• Passaggio 2: installare pip e Sphinx
• Passaggio 3: impostare la configurazione di base per la documentazione
• Passaggio 4: costruire la gerarchia per la documentazione
• Passaggio 5: creare i file di origine specificati sopra
• Passaggio 6: produrre la versione HTML della documentazione

Sphinx è un utile strumento basato su Python per tecnici e scrittori che consente loro di creare facilmente documentazione elegante e completamente funzionale in vari formati. Con Sphinx, scrivi documenti utilizzando reStructuredText - un linguaggio di markup leggero - per cominciare, quindi puoi ottenere l'output in più formati, tra cui HTML, LaTeX, PDF, ePub e altri.

In questo tutorial, tratteremo il processo di installazione e utilizzo Sphinxsu un'istanza di CentOS 7 x64 sulla piattaforma di Vult.

Prerequisiti

• Un'istanza di CentOS 7 x64.
• Un utente sudo .

Passaggio 1: aggiornare il sistema

sudo yum update
sudo shutdown -r now

Passaggio 2: installare pip e Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Passaggio 3: impostare la configurazione di base per la documentazione

Prima di iniziare a utilizzare Sphinx, è necessario specificare la directory di origine in cui Sphinxverrà eseguita e salvare tutta la documentazione. Dopo aver creato la directory che si intende utilizzare, è quindi possibile eseguire sphinx-quickstartciò che inizializzerà Sphinxe creerà la configurazione di base richiesta.

sphinx-quickstart è simile a una procedura guidata di installazione che ti chiederà domande che determinano gli aspetti del tuo progetto.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Passaggio 4: costruire la gerarchia per la documentazione

Per impostazione predefinita, la sphinx-quickstartprocedura guidata creerà diverse directory e file.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

Diamo un'occhiata al file principale index.rst, che contiene la gerarchia della tua documentazione; vale a dire, l'albero del sommario o toctree.

Aprilo con un editor di testo:

vi index.rst

Mentre rivedi il file, noterai una sezione chiamata toctree. Se hai altri file sorgente ( *.rst) per la tua documentazione, dovrai specificarli nella toctreesezione: .. toctree ::: maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

È indispensabile:

• Lascia una riga vuota sopra il tuo input.
• Non aggiungere suffissi ai file di origine .rst.
• Inserisci i tuoi file sorgente nel loro rispettivo ordine.
• Utilizzare solo un nome file per riga.
• Rientra i nomi dei tuoi file con :maxdepth: 2.

Dopo aver completato le modifiche, salvare il file e chiudere l'editor di testo.

ESC
:!wq

Passaggio 5: creare i file di origine specificati sopra

I file di origine devono essere creati con nomi che corrispondono a quanto precedentemente specificato index.rst, altrimenti non verranno inclusi nell'output finale.

Tutti i file di origine devono essere compatibili con reStructuredText markup language. Per ulteriori informazioni, fare riferimento a reStructuredText Primer .

Passaggio 6: produrre la versione HTML della documentazione

Una volta terminata la composizione della documentazione, è possibile HTML format eseguire il lavoro eseguendo il comando seguente:

make html

L'output verrà salvato nella directory ./\_build/htmlche include tutto il necessario per visualizzare il file in una navigazione web.

Questo conclude il nostro tutorial.