Il lavoro da fare su Github

Con il metodo proposto in questo tutorial, il lavoro che c’è da fare sull’account di      è il seguente.


1. Creare il nome del progetto

Creare il nome del progetto.

Scrivere nel file READ.ME la descrizione di cosa contiene quel progetto (un po di metadatazione del progetto). Come nel caso del file READ.ME di questo tutorial.

Il nome del progetto sarà richiamato dal plugin GGeditor una volta richiamato l’account Github ed editati user e password. Appariranno su un pannello i vari repository Github del nostro account e si sceglierà quello a cui inviare i Google Doc ai quali lavoreremo.


2. Creare un file “conf.py”

Creare un file dandogli il nome conf.py e all’interno incollare il seguente codice

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
# -*- coding: utf-8 -*-

from __future__ import unicode_literals
import sys, os

on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

sys.path.append(os.path.abspath(os.pardir))

__version__ = '1.0'

# -- General configuration -----------------------------------------------------

source_suffix = '.rst'
master_doc = 'index'
project = 'CHANGE-THIS'
copyright = '2016, CHANGE-THIS'

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

extlinks = {}

# -- Options for HTML output ---------------------------------------------------

html_theme = 'default'

html_static_path = ['static']

def setup(app):
    # overrides for wide tables in RTD theme
    app.add_stylesheet('theme_overrides.css') # path relative to static

"""
  You might want to uncomment the “latex_documents = []” if you use CKJ characters in your document.
  Because the pdflatex raises exception when generate Latex documents with CKJ characters.
"""
#latex_documents = []

# inserire un logo in alto a sinistra (mettendo l’immagine nella cartella “static”)
latex_logo = "static/immagine.jpg"
html_logo = "static/immagine.jpg"

Importante

Nella pagine del codice sostituire i seguenti parametri:

project = 'CHANGE-THIS'

al posto di CHANGE-THIS (dentro gli apici) editare il nome del titolo progetto che si vuole far comparire su Read the Docs;

copyright = '2016, CHANGE-THIS'

al posto di CHANGE-THIS (dentro gli apici) editare il tipo di licenza che si intende adottare per il rilascio della pubblicazione su Read the Docs.

Creare il logo in alto a sinistra

Se si vuole far visualizzare un logo sulla parte in alto a sinistra, si procede in questo modo: alla fine del codice del file conf.py, bisogna scrivere:

latex_logo = "static/immagine.jpg"
html_logo = "static/immagine.jpg"

dove immagine.jpg sarà l’immagine da visualizzare in alto a sinistra (logo del nostro progetto), che metteremo dentro la cartella static.


3. Creare il file “theme_overrides.css” e inserirlo dentro la cartella “static”

Il file theme_overrides.css serve per modificare la grafica base del file conf.py.

Serve anche per ottimizzare la visualizzazione delle tabelle ampie sulle pagine HTML di Read the Docs.

Si crea questo file dentro la directory static. Basta copiare il codice qui di seguito descritto in un file che chiameremo, appunto, theme_overrides.css dentro la cartella static.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
.wy-table-responsive table td, .wy-table-responsive table th {
   white-space: inherit;
}

.wy-table-responsive table th {
   background-color: #f0f0f0;
}

.line-block, .docutils.footnote {
    line-height: 24px;
}

.admonition {
    margin-bottom: 20px;
    line-height:24px;
}

.admonition > *:not(:first-child){
    /* draw a boder around a admonition */
    border-left: solid 1px #b59e9e;
    border-right: solid 1px #b59e9e;
    padding: 12px;
    margin: -12px -12px -12px -12px;
    margin-bottom: -12px !important;
}
.admonition > .last, .admonition- > .last{
    /* draw a boder around a admonition */
    border-bottom: solid 1px #b59e9e !important;
}

/* adatta il nav-content a fullhd e si elimina lo spazio vuoto piccolo a destra */
.wy-nav-content {max-width: 1920px;}

(guarda qui).

L’istruzione .wy-nav-content {max-width: 1920px;} consente di estendere per tutta la larghezza del monitor lo spazio in cui viene visualizzato il testo, dando una sensazione grafica gradevole all’intero documento.


Come fare leggere un file in formato .MD a ReadtheDocs (in un progetto su Github)

(ricetta su Tansignari)

Se voglio far leggere un file .MD a Read the Docs, oltre ai file .RST, quali impostazioni devo settare e dove li devo settare su Github?

Bisogna guardare questi due file requirements.txt e conf.py sul progetto ospitato da Github.

requirements.txt

requirements.txt è il file che contiene i requisiti dei moduli da installare. Vedi ad esempio: https://github.com/opendatasicilia/tansignari/blob/master/requirements.txt. Bisogna inserire queste istruzioni di seguito elencate nel file:

sphinx-rtd-theme
sphinx
recommonmark
markdown
sphinx-markdown-tables

conf.py

conf.py è il file di configurazione in linguaggio Python. In queste linee si imposta la configurazione che abilita il Markdown (.MD) su Read the Docs.

import recommonmark
from recommonmark.transform import AutoStructify

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}

source_suffix = ['.rst', '.md']

extensions = ['sphinx.ext.ifconfig','sphinx_markdown_tables']

Bisogna inserire queste righe di codice nel file conf.py.


Una configurazione leggera ed efficace

Con le tre azioni di sopra si conclude tutto il lavoro da svolgere su Github, quindi questa soluzione si presta a chi non ha dimestichezza con il linguaggio RST.

Una configurazione del progetto Github molto leggera ma efficace in termini di risultati di pubblicazione di un documento sul design Read the Docs.

IMG1

Come si nota dall’elenco dei file che vengono generati dal plugin GGeditor direttamente nel repository Github abbiamo:

  • un file README.md che è un file di descrizione del progetto, che provvediamo a editare noi su Github per far capire al lettore che cosa contiene il repository Github in questione. Questo file lo creiamo noi;
  • il file conf.py che contiene il codice con indicazioni necessarie all’esposizione dei Google Docs sulla piattaforma di Read the Docs. Il codice del file “conf.py” viene fornito nel tutorial di GGeditor. Basta creare un file nel repository Github, dargli il nome di conf.py e fare un copia e incolla dal paragrafo del tutorial di GGeditor. Questo file lo creiamo noi;
  • una directory static che contiene soltanto immagini .png che sono le immagini che incolliamo nel Google Doc e che nell’azione del “Commit”, avviata dal plugin GGeditor, vengono generate automaticamente e inviate nella cartella static. Questa cartella static viene generata automaticamente dal plugin GGeditor;
  • il file theme_overrides.css che creeremo dentro la directory static.
  • i file .rst che sono i Google Doc convertiti automaticamente in file .rst dal plugin GGeditor e inviati nel repository Github. Questi file vengono generati dal componente aggiuntivo di Google doc, GGeditor;

Dalla descrizione di questi file si comprende come l’intero pacchetto su Github è molto semplice come tipologia di file. L’unico più complesso da capire è il contenuto del file conf.py e del file theme_overrides.css ma sono file che non dobbiamo nemmeno creare, perchè copiamo i contenuti dei file dal tutorial, andando a cambiare al suo interno solo il “nome” del documento da pubblicare e “il tipo di licenza” (questo solo nel file conf.py) e aggiungendo il nome del file immagine qualora volessimo creare un logo del progetto da far visualizzare in alto a sinistra sul progetto di Read the Docs.


Inserire un logo in alto a sinistra nel design Read the Docs

Per inserire un immagine in alto a sinistra nel design di “Read the Docs”, per creare il logo del nostro progetto, basta andare nel file conf.py e alla fine inserire questo codice:

latex_logo = "static/immagine.png"
html_logo = "static/immagine.png"

avendo cura di caricare il file immagine.png nella cartella static.

Attenzione

Queste istruzioni non possono essere dati ai documenti da pubblicare in stile Docs Italia, ma solo ai documenti da pubblicare nello stile di base Read the Docs.


Inserire la freccia “back to the top” nella pagina HTML

IMG2

Al fine di permettere di risalire rapidamente in alto nella pagina HTML, torna comoda l’icona a forma di freccia sulla parte destra in basso della stessa pagina.

Di seguito la procedura per ottenere la freccia “back to the top” sulla pagina HTML.

Creare la cartella _templates e all’interno di essa creare il file layout.html e copiare il seguente codice:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<link href="{{ pathto("_static/theme_overrides.css", True) }}" rel="stylesheet" type="text/css" />

<!-- css back top -->
<!--<link href="../_static/jquerysctipttop.css" rel="stylesheet" type="text/css" />-->
<link href="{{ pathto("_static/jquerysctipttop.css", True) }}" rel="stylesheet" type="text/css" />
<!--<link href="../_static/backTop.css" rel="stylesheet" type="text/css" />-->
<link href="{{ pathto("_static/backTop.css", True) }}" rel="stylesheet" type="text/css" />
<!-- Script -->
<!--<script type="text/javascript" src="../_static/jquery.min.js"></script> -->
<script type="text/javascript" src="{{ pathto("_static/jquery.min.js", True) }}"></script>
 {% endblock %}


{% block footer %}
      {{ super() }}
       <!-- script Back To Top  -->
      <div class="footerc">
          <a id='backTop'>Back To Top</a>
 <!-- script toptoback automatico mobile/desktop -->
 <!-- <script type="text/javascript" src="../_static/jquery.backTop.min.js"></script> -->
<script type="text/javascript" src="{{ pathto("_static/jquery.backTop.min.js", True) }}"></script>
<script>
            $(document).ready( function() {
                $('#backTop').backTop({
                    'position' : 400,
                    'speed' : 300,
                    'color' : 'green', <!-- lo sfondo freccia è di colore verde -->

                                                    });
            });
        </script>
      </div>

{% endblock %}

Nella cartella static creare i file:

copiando il codice dai rispettivi file dei link di sopra.

Sempre dento la cartella static, bisogna inserire un’immagine (con la freccia in alto) come questa contenuta qui dentro.

E infine non dimenticare di inserire nel file conf.py alla fine delle righe, il seguente codice:

templates_path = ['_templates']

Inserire lateralmente icone per la condivisione delle pagine HTML di Read the Docs sui social network

Al fine di permettere la condivisione delle pagine del documento Read the Docs sui social network, una delle soluzioni che graficamente si adatta meglio alla grafica delle pagine RTD è fornita dalla piattaforma gratuita https://www.addthis.com. Una volta creato l’account su addthis è possibile creare icone personalizzate (colore, dimensione) per la visualizzazione delle stesse sulle pagine html di RTD. Una volta creato il banner, sempre nella piattaforma addthis andare su “get the code” e copiare il codice che viene fornito. Tale codice è di questo tipo

<!-- Go to www.addthis.com/dashboard to customize your tools -->
<script type="text/javascript" src="//s7.addthis.com/js/300/addthis_widget.js#pubid=ra-5b4c36adc4260026"></script>

e va incollato nella pagina layout.html (dentro la cartella _templates) prima di {% endblock %}. Tutto qui.


Inserire in fondo alla pagina HTML del progetto Read the Docs lo spazio Disqus per i commenti

È possibile inserire in fondo alla pagina HTML del progetto Read the Docs uno spazio destinato ai commenti degli utenti, come avviene per tantissimi blog.

Uno dei servizi online gratuiti e molto diffusi è Disqus. È necessario creare un account su questo servizio e creare un progetto con lo stesso nome del progetto Read the Docs.

Per ogni progetto creato su Disqus verrà fornito il seguente codice da inserire nella pagina footer.html:

<p>
<script id="dsq-count-scr" src="//guida-readthedocs.disqus.com/count.js" async></script>
<div id="disqus_thread"></div>
<script>
/**
*  RECOMMENDED CONFIGURATION VARIABLES: EDIT AND UNCOMMENT THE SECTION BELOW TO INSERT DYNAMIC VALUES FROM YOUR PLATFORM OR CMS.
*  LEARN WHY DEFINING THESE VARIABLES IS IMPORTANT: https://disqus.com/admin/universalcode/#configuration-variables*/
/*

var disqus_config = function () {
this.page.url = PAGE_URL;  // Replace PAGE_URL with your page's canonical URL variable
this.page.identifier = PAGE_IDENTIFIER; // Replace PAGE_IDENTIFIER with your page's unique identifier variable
};
*/
(function() { // DON'T EDIT BELOW THIS LINE
var d = document, s = d.createElement('script');
s.src = 'https://guida-readthedocs.disqus.com/embed.js';
s.setAttribute('data-timestamp', +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
</p>

dove la parte guida-readthedocs deve essere sostituita con il nome del progetto specifico individuato su Disqus per il documento da pubblicare con lo stile “Read the Docs”.

Il codice sopra illustrato deve essere inserito nella pagina footer.html prima delle seguenti righe di codice:

    {%- block extrafooter %} {% endblock %}

</footer>

Guarda direttamente al file footer.html su GitHub per comprendere meglio.


Cambiare il colore di sfondo del rettangolo in alto a sinistra

Cambiare colore sul rettangolo superiore in alto a sinistra, dove è situato il nome del progetto, è possibile. Qui di seguito si riporta il codice da inserire sul file theme_overrides.css che si trova dentro la cartella static:

}

.wy-side-nav-search {
    background-color: #525e99;
}

il codice “#525e99“ usato in questo caso (il colore del rettangolo in alto a sinistra del tutorial che state leggendo) corrisponde alla tonalità cromatica verificabile a questo link:https://www.color-hex.com/color/525e99. Ovviamente cambiando codice numerico (con #iniziale) è possibile generare altre tonalità da applicare al caso specifico.

Attenzione

Queste istruzioni non possono essere dati ai documenti da pubblicare in stile Docs Italia, ma solo ai documenti da pubblicare nello stile di base Read the Docs.


Cambiare il colore dei titoli dei capitoli, paragrafi, sottoparagrafi, ecc.

Come prima, è anche possibile cambiare il colore dei titoli dei capitoli, paragrafi, sottoparagrafi, ecc. Sempre sul file theme_overrides.css si riporta il seguente codice:

}

h1, h2, h3 {
    color: #176a90 !important;
}

il codice “#176a90” può essere cambiato con i codici di tantissimi altri colori disponibili.

Attenzione

Queste istruzioni non possono essere dati ai documenti da pubblicare in stile Docs Italia, ma solo ai documenti da pubblicare nello stile di base Read the Docs.


Inserire una barra di scroll orizzontale in alto nella pagina

Al fine di far visualizzare al visitatore della pagina a che livello (sull’intera pagina) è arrivato nella lettura, torna utile inserire un piccolo sottile scroll orizzontale da posizionare in alto.

Bisogna fare due cose. Prima cosa: incollare nel file layout.html il seguente codice, prima della riga in cui si trova {% endblock %}:

<!-- Reading Progress Bar on Scroll -->
<!-- vedere questo repo per progress bar: https://github.com/mburakerman/prognroll -->
<script type="text/javascript" src="{{ pathto("_static/prognroll.js", True) }}"></script>
<script>
     $(function() {
       $("body").prognroll({
         height: 4, //Progress bar height in pixels
         color: "#3337c4", //Progress bar background color
       });
    });
</script>

dove

  • height’ è l’altezza della barra dell scroll
  • color’ è il codice del colore che vogliamo assegnare alla barra dello scroll. A questo link è possibile scegliere i codici di una vasta gamma di colori da utilizzare.

Seconda cosa da fare: creare un file Java Script prognroll.js nella cartella static dove inserire questo codice.


Uno schema tipo di progetto Github che raccoglie tutte le funzioni illustrate in questa pagina del tutorial

Asino siciliano

A questa pagina di Github https://github.com/cirospat/rtd-schematipo si trova uno “schema tipo” di repository la cui restituzione come progetto Read the Docs è disponibile qui: https://schema-tipo.readthedocs.io.

Lo schema tipo Github può essere clonato per creare un altro progetto Github che abbia le stesse impostazioni, che graficamente sono visibili nel relativo progetto Read the Docs.

Quindi la funzione dello schema tipo Github è quella di facilitare tutte le procedure di editing del codice, non dovendo pensare a crearlo da zero, e dando la possibilità all’utente di cambiare le personalizzazioni (titolo del progetto e versione della licenza nel file conf.py, colore testo dei capitoli/paragrafi, colore del riquadro in alto a sinistra e altre impostazioni nel file theme_override.css dentro la cartella static) e di concentrarsi maggiormente sui contenuti (testo, immagini, video,..) della pubblicazione che saranno editati direttamente dentro i Google doc.