Il lavoro da fare su Github

Con il metodo proposto in questo tutorial, il lavoro che c’è da fare sull’account di   Github   è 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

# -*- coding: utf-8 -*-

from __future__ import unicode_literals
import sys, os
import re

from sphinx_rtd_theme import __version__ as theme_version
from sphinx_rtd_theme import __version_full__ as theme_version_full


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 = 'sphinx_rtd_theme'

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.

.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.

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

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:

<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:

• jquerysctipttop.css

• backTop.css

• jquery.min.js

• jquery.backTop.min.js

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.

Aggiungere un’immagine dinamica in stile Word Cloud (WordArt)

Con https://wordart.com è possibile creare immagini composte da parole che al passaggio del mouse vengono evidenziate.

Cosa fare per incorporare queste word cloud dentro una pagina HTML del progetto Read the Docs?

1. Attivare un account su https://wordart.com e cominciare a creare un progetto. Si può importare l’elenco delle parole anche da una pagina web tramite l’URL.

2. Nel file layout.html del progetto Github inserire lo script: <script src="//cdn.wordart.com/wordart.min.js" async defer></script>.

3. Nella pagina di Google doc di interesse inserite il codice che https://wordart.com vi dà dopo la creazione del vostro progetto. In ordine: Salvate il vostro progetto (save) - Andate su “share” quindi cliccate su “Embed on a webpage”.

4. Copiate il codice, che dovrebbe essere di questo tipo <div style="width: 400px; height: 400px;" data-wordart-src="//cdn.wordart.com/json/e9h2wyb41pzf" data-wordart-show-attribution></div>, sulla pagina Google doc tramite la funzione HTML del pannello Markup di GGeditor. Quindi fate il solito commit su GGeditor che trasmetterà la nuova funzione a Github e così automaticamente vedrete sulle pagine HTML di Read the Docs la vosytra nuova Word Cloud

Ecco la Word Cloud

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.

Inserire il popup eu-cookie nei progetti «read the docs»

(istruzioni a cura di Giovan Battista Vitrano)

Per aggiungere il popup eu-cookie per dare visibilità dei contenuti concernenti la privacy, basta aggiungere i tre file script di seguito elencati nella cartella static del progetto Github:

• jquery-2.1.3.min.js

• jquery-eu-cookie-law-popup.js

• jquery-eu-cookie-law-popup.css

Inserire nel file layout.html (nel blocco principale) il codice html:

<!--eu-cooki-lawt →
<!-- <script type="text/javascript" src="{{ pathto("_static/jquery-2.1.3.min.js", True) }}"></script>  -->
<script type="text/javascript" src="{{ pathto("_static/jquery-eu-cookie-law-popup.js", True) }}"></script>
<link href="{{ pathto("_static/jquery-eu-cookie-law-popup.css", True) }}" rel="stylesheet" type="text/css" />

Sempre nel file layout.html inserire il seguente codice:

<div class="eupopup eupopup-top "></div>

Guarda il file su GitHub per il corretto inserimento del codice.

Per modificare il testo del popup, apri il file jquery-eu-cookie-law-popup.js con notepad++, o anche con il semplice notepad, e cerca il blocco PARAMETERS (MODIFY THIS PART), e li modifichi url della pagina privacy ed il testo:

// PARAMETERS (MODIFY THIS PART) ///////////////////////
_self.params = {
cookiePolicyUrl : 'https://cirospat.readthedocs.io/it/latest/privacy.html',
popupPosition : 'top',
colorStyle : 'default',
compactStyle : false,
popupTitle : 'Questo sito web utilizza i cookie, anche di terze parti, per migliorare la vostra esperienza di navigazione web.',
popupText : 'Chiudendo questo banner, scorrendo questa pagina o cliccando su qualunque suo elemento acconsenti all’uso dei cookie. Per maggiori informazioni o per negare il consenso a tutti o ad alcuni cookie, consulta l’informativa.',
buttonContinueTitle : 'Chiudi!  ',
buttonLearnmoreTitle : 'Leggi l’informativa',
buttonLearnmoreOpenInNewWindow : false,
agreementExpiresInDays : 30,
autoAcceptCookiePolicy : false,
htmlMarkup : null
};

Ricordati (!) che devi aggiungere nel tuo progetto “Read the Docs” la pagina dell”informativa privacy. Ovviamente questa pagina HTML sarà del testo preventivamente editato su un Google doc.

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.