images/wallpaper.png

Help

Qui troverai tutto quello che serve per installare Sphinx e creare pagine HTML

Modify .rst

Questo punto del help mostra come tutti possono inserire le loro risorse partendo dalla nostra repository senza avere problemi

git clone https://github.com/eagletrt/eagletrt.github.io.git
cd eagletrt.github.io/EAGLEDOC

La cartella EAGLEDOC contiene tutti i file sorgente e multimediali che ci servono per generare gli html. Una volta modificato un file, inserito nell index.rst o dove è necessario basterà prepararli per la repo. Questi una volta che saranno pronti per la pubblicazione (vedi ultimo punto se vuoi sapere come funziona, altrimenti copia-incolla-invio) Per poi essere copiati e incollati nela directory principale (eagletrt.github.io)

sudo python sphinxtogithub.py build/html

Verifichiamo le modifiche effettuate se ci torna tutto possiamo procedere

git status

Aggiungiamo, scriviamo un messaggio, pushiamelo!

git add .
git commit -m "Ho fatto questo e quello"
git push origin master

Install Sphinx

sudo apt-get install python-sphinx
mkdir sphinx-project
cd sphinx-project

Create a Project

sphinx-quickstart

Ora da terminale verrà richiesto di creare il progetto e bisognerà completare questi campi:

*Project Name

*Author Name

*Project version

Gli altri basterà skipparli con enter. Una volta terminata la creazione dei file necessari bisogna testare se è andato tutto a buon fine aprendo in _build/html l’index.html

Create a file.rst

Per generare nuove pagine bisogna creare un nuovo file .rst dove andranno scritti tutti i tag

touch file.rst

Ora passo a passo verrano mostrati i comandi necessari per creare una pagina:

  • Per quanto riguarda il titolo basterà scriverlo e nella riga sottostante mettere tanti “=” quanto la lunghezza della stringa del titolo

  • Per aggiungere immagini alla pagina basterà creare una directory nella cartella del progetto e inserire le immagini

    .. image:: immagine

    Esempio:

    .. image:: /images/wallpaper.png
    
  • Per aggiungere scritte testuali basterà scrivere il testo e verrà visualizzato

  • Per aggiungere note

    .. note::

    Esempio:

    .. note::
    
                    this is a note
    
  • Per aggiungere warning

    .. warning::

    Esempio:

    .. warning::
    
                    this is a warning
    
  • Per aggiungere codice basterà specificare il tipo di linguaggio

    .. code-block:: linguaggio

    Esempio:

    .. code-block:: sh
    
                    this is a code
    
    • Per rendere visualizabile la pagina html basterà in index.rst linkare il file inserendo in Contents il nome senza estensione ad esempio file

Build Project

Ora per creare effettivamente i file html si usa il comando make

sudo make clean
sudo make html

Per aprire il sito bisogna spostarsi su _build/html e aprire index.html

Themes From GitHub

Se non ancora installato scaricare pip oppure skippare al secondo comando

sudo apt-get install python-pip
pip install sphinx_rtd_theme

In conf.py modificare come segue

*import sphinx_rtd_theme

*html_theme = “sphinx_rtd_theme”

*html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Questa procedura viene utilizzata per scaricare in locale sul pc ma effettivamente non vengono caricati i file nella directory del progetto, esiste un altro modo per caricarlo basta guardare su sphinx-doc dove oltre a questo è possibile vedere tutti i comandi che ho illustrato qui e inoltre è possibile vedere i file source di ogni singola pagina per impararne di nuovi.

Output To Git Hub

Una volta creati gli .html desiderati bisognerà utilizzare uno script per sistemare le reference che utilizza GitHub, ci sono tantissimi modi, io consiglio questo script. Una volta clonato il progetto basterà seguire le istruzioni che trovate nella repo di michaeljones.

git clone https://github.com/michaeljones/sphinx-to-github
sudo python /sphinx-to-github/sphinxtogithub/sphinxtogithub.py ~/eagletrt.github.io/EAGLEDOC/build/html