Il lavoro da fare su Read the Docs
Questa rappresenta la fase finale del lavoro ed è molto semplice come operazioni da effettuare. Una volta completato il lavoro di compilazione su Github, bisogna andare su http://readthedocs.io e (dopo aver creato il relativo account) importare il progetto, già creato, da Github.
Nella finestra, su “URL del Deposito Codice”, bisogna scrivere l’URL del progetto che avete creato su Github, e quindi scegliere il nome del progetto, ad esempio:
“linee guida open data comune vattelapesca”
e lasciare “Tipo del Deposito Codice” selezionato su “Git”.
A quel punto verrà messo in collegamento il vostro progetto di Github con il progetto su Red the Docs.
Una primissima azione da compiere è andare su “Amministrazione” e settare la lingua italiana. Questo consentirà a Read the Docs di aggiungere al titolo del vostro progetto la desinenza /it/latest. Il documento è in italiano quindi prende la desinenza /it. Questa impostazione permetterà alle note colorate che avete creato su Google doc di avere un titolo italiano (“Nota” al posto di “Note”, “Avvertimento” al posto di “Warning”, “Attenzione” al posto di “Attention” ecc.).
Esempio: come-creare-guida.readthedocs.io/it/latest
A questo punto il progetto di Github è compilato su Read the Docs.
Considerato che avevamo scelto come titolo del nostro progetto su Read the Docs: “linee guida open data comune vattelapesca”, l”URL compilato da Read the Docs per vedere il nostro progetto sarà:
linee-guida-open-data-comune-vattelapesca.readthedocs.ioMessaggi di ‘passing’ e ‘failing’ sul pannello di controllo di Read the Docs
Avviso di passing
Procedura andata a buon fine: «passing»
Se non ci sono errori commessi durante le procedure spiegate fino ad ora, tutto andrà a buon fine, e Read the Docs darà il messaggio in colore verde di «passing» al nostro progetto, significa che il nostro progetto è - quindi - online. La compilazione (build) su Read the Docs avviene con successo e ogni modifica che effettuiamo sul file del Google doc, viene commissionato a Github e compilato in tempo reale su Read the Docs, apparendo immediatamente sulle pagine HTML. La “build” su Read the Docs viene eseguita correttamente.
Avviso di failing
Procedura con Errore: «failing»
Se sono stati commessi errori nella procedura finora illustrata, Read the Docs alla sezione “i miei progetti”, darà un messaggio in colore rosso di «failed». In questo caso c’è qualche problema da qualche parte e bisogna ripercorrere tutti i passaggi fatti da quando si è iniziato a lavorare a partire dai file su Google doc fino a quanto eseguito sul sito di Read the Docs.
La compilazione su Read the Docs ha incontrato qualche problema, e quando si presenta questo caso la prima cosa da fare è andare nel file conf.py - dentro il repository del progetto su Github - e verificare le istruzioni date dentro questo file. Generalmente se si presenta un problema nella compilazione di Read the Docs, il problema sta dentro questo file. Una volta individuato e risolto il problema, Read the Docs comincerà automaticamente a compilare le istruzione del file conf.py di Github e dara il bollino verde di «passed» (cioè la compilazione è effettuata con successo).
Abbiamo completato tutte le procedure e ci possiamo godere il nostro documento nella nuova modalità di pubblicazione e visualizzazione con lo stile Read the Docs o con il design Docs Italia.
[Questa pagina è ripresa da quella del tutorial “Tutorial pubblicazione Read the Docs su DocsItalia” (a cura di Pablo Persico, Andrea Borruso e Ciro Spataro) ed ulteriormente arricchita].
Messaggio Read the Docs di “build fails”: [cannot import name “PackageFinder” from “pip._internal.index”]
Può capitare che durante la procedura di compilazione del progetto su RTD appaia un messaggio:
“cannot import name “PackageFinder” from “pip._internal.index”.
La causa
Currently all builds are failing because the automatic upgrade (since #4823) to pip 20.0 was buggy (see pypa/pip#7620). There’s now a 20.0.1 release which seems to have fixed the problem for others … but how can I force my readthedocs to also upgrade to the .1 version?
La soluzione (da Read the Docs / Wiping a Build Environment):
Sometimes it happen that your Builds start failing because the build environment where the documentation is created is stale or broken. This could happen for a couple of different reasons like pip not upgrading a package properly or a corrupted cached Python package.
In any of these cases (and many others), the solution could be just wiping out the existing build environment files and allow Read the Docs to create a new fresh one.
Follow these steps to wipe the build environment:
Go to Versions
Click on the Edit button of the version you want to wipe on the right side of the page
Go to the bottom of the page and click the wipe link, next to the “Save” button
Note: By wiping the documentation build environment, all the rst, md, and code files associated with it will be removed but not the documentation already built (HTML and PDF files). Your documentation will still be online after wiping the build environment.
Now you can re-build the version with a fresh build environment!
Web Analytics - inserire il codice su
E’ possibile agganciare strumenti di web analytics ai progetti online di Read the docs. Se si usa, ad esempio Google Analytics, una volta creato il progetto specifico su Google Analytics, si ottenuto il codice. Il codice va inserito nel progetto specifico nel pannello di Amministrazione di read the docs, seguendo questo percorso:
Amministrazione / Impostazioni avanzate, e andando in fondo alla pagina fino alla voce Codice Analytics, quindi cliccare il testo ‘salva’.