Dunque ho dovuto per forza usare sphinx perché il tool che avevo intenzione di usare cioè rst2pdf e rst2html5 hanno qualche problema soprattutto a covertire i tag per python come :func:`curses.window` in quanto non li riconosce. Quindi ho installato sphinx e dopo aver risolto una sfilza di errori ho comunque lo stesso problema che non mi riconosce i tag python... ne come func:`mia.funzione` ne senza . Con rst2html5 mi rende poi proprio il documento non fruibile in quanto piazza dei rettangoli di errore in mezzo al documento. Mentre almeno sphinx non mi da l'errore nel documento ...

Sai come risolvere ?

Se proprio ci devo perdere del tempo mi faccio uno script awk per convertire tutti gli indirizzi. La cosa buffa è che ovviamente non digerisce nemmeno il documento originale di python.org. Sphinx però non l'ho installato con pip in quanto per me tutto quello che è fuori dal sistema ufficiale di pacchettizzazione è il diavolo.

Ho sospetto che per usare sphinx occorra prima studiare a fondo la documentazione di sphinx... non è quel genere di strumento che "funziona alla cieca", la prima volta che ci provi... come ti dicevo, non è un "programma" per l'utente finale, è una libreria per programmatori, e ha il suo modello concettuale da capire. Tieni conto che, probabilmente ti servirà anche l'estensione intershinx per risolvere i rimandi a oggetti che sono documentati nel resto della documentazione (inglese) di python.


A dire il vero non ho trovato particolari difficoltà a risolvere i nomi del dominio "python" con sphinx e intersphinx, quando traducevo il tutorial. Mi è bastato aggiungere intersphinx alla macchina: https://github.com/ricpol/pytutorial-it/blob/master/tutorial/source/conf.py#L34

> Con rst2html5 mi rende poi proprio il documento non fruibile in quanto piazza dei rettangoli di errore in mezzo al documento

Questo sarà probabilmente un problema di encoding?

> La cosa buffa è che ovviamente non digerisce nemmeno il documento originale di python.org

Mi sembra abbastanza logico... se non ha un riferimento per dove trovare gli oggetti, non può inventarselo. E' anche per questo che viene comodo intersphinx.

> Se proprio ci devo perdere del tempo mi faccio uno script awk per convertire tutti gli indirizzi.


Ecco, questa sì che sarebbe una cattiva idea. Anche se ci riuscissi (e come, poi? dovresti in pratica replicare l'algoritmo di sphinx... ma allora usa sphinx), sarebbe una cosa che azzera completamente la portabilità del tuo lavoro. Il consiglio è sempre quello di imparare a fare le cose nel modo giusto (con il disclaimer già detto, ovviamente, che poi ciascuno fa come gli pare).


> Sphinx però non l'ho installato con pip in quanto per me tutto quello
che è fuori dal sistema ufficiale di pacchettizzazione è il diavolo.


Ok, hai definitivamente delle idee... particolari, diciamo. Poi non capisco che cosa intendi con "fuori dal sistema ufficiale di pacchettizzazione"... Mah... comunque, sphinx si installa come tutti i pacchetti python: con Pip, dentro un virtual environment. Questo è il modo più "ufficiale" che c'è (e anche quello giusto, per quel che vale).

Dunque credo di aver risolto, ora sto scegliendo che tema usare ed ho anche aggiunto l'estensione per aggiungere il bottone per copiare il codice.

Il tuo file di configurarezione conf.py mi è stato di grande aiuto.. e non hai citato che bisogna anche aggiungere la direttiva

intersphinx_mapping = {'py': ('https://docs.python.org/3', None)}

che infatti ho trovato nel tuo file.

Ora mi devo occupare dei pdf che anche qui mi da problemi.

Il mio script awk non azzererebbe la portabilità del lavoro in quanto si occuperebbe di convertire i vari :func:`blahblah` in link tipo **`curses https://docs.python.org/3.8/library/curses.html#module-curses`_ ** che sia sphynx che rst2html e rst2pdf digeriscono senza problemi.

Non so se conosci awk, è un comando linux, oppure un vero proprio linguaggio per processare testo che è stato scritto da Brian Kernighan. Quest'ultimo insieme a Dennis Richie (l'inventore del C) hanno scritto un famosissimo volume sul funzionamento e l'apprendimento del c. Ritchie è anche noto per aver scritto il primo UNIX.

Per "fuori dal sistema ufficiale di pacchettizzazione" intendo che non rientra in apt il sistema di pacchettizzazione di ubuntu e debian. E' importante evitare di installare cose fuori da apt per evitare di avere un sistema ibrido. Avere un sistema ibrido puo' portare ad avere un sistema incasinato cioè instabile, in quanto apt non sa che librerie/app varie sono installate, questo ovviamente se usi pip da root. Se usi virtualenv le cose stanno un po' meglio in quanto venv crea un ambiente virtuale parallelo al tuo sistema installato quindi eviti di avere configlitti di versioni o librerie di versioni differenti sparse in giro. Altra cosa da evitare è quello di installare roba da sorgenti, per le stesse identiche ragioni. Se hai un server puoi anche usare i sorgenti ma solo nel caso in cui sai che su quel sistema c'è solo quel software installato, un sistema desktop non è adatto a questo tipo di mix.

Un altra ragione per evitare di uscire dal sistema ufficiale di pacchettizzazione è il fatto che apt conosce non solo tutto quello che è installato ma anche tutti gli hash di ogni singolo file. In questo modo puoi fare un test di sicurezza molto veloce e affidabile per capire se qualche libreria/file/eseguibile/driver/backdoor/ecc è stato illecitamente sostituito/aggiunto/rimosso dal sistema.

Quindi usare pip o i sorgenti, specialmente da root, è veramente una cosa pessima, che chiunque dovrebbe evitare.

Usare venv è un po meglio perché se hai sospetti di intrusioni varie cancelli la cartella e reinstalli... ma comunque è una cosa veramente poco elegante perché è come avere un software portable in ambiente windows.. si c'è ma è una cosa che si porta dietro un po' di svantaggi perché ovviamente ha le sue librerie, quindi ti occupa una barca di spazio e in più è ovviamente più lento. Ci sono moti dev che lo usano come sistema ma viene usato come ambiente temporaneo e per debug... tutti i software che raggiungono una certa stabilità e importanza vengono pacchettizzati. Per tutte le ragioni che ho spiegato.

Le mie idee non sono le mie idee sono le idee che la comunità linux si porta dietro da 30 anni che evidentemente sono idee che funzionano visto che google con android si è "inventato" il play store e lo stesso hanno fatto apple e microsoft.

> non hai citato che bisogna anche aggiungere la direttiva

era due righe sotto... ;-) e comunque la documentazione di interpshinx è sempre a portata di mano, eh? https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

> Ora mi devo occupare dei pdf che anche qui mi da problemi.


Nella traduzione del tutorial non mi sono preoccupato del problema, perché lascio che ci pensi ReadTheDocs a queste cose... che è una delle (molte) ragioni per cui consiglio di usare strumenti e flussi di lavoro già consolidati e testati, piuttosto di farsi le cose daccapo...
Tuttavia nel processo di lavoro dei miei libri, effettivamente, devo generare il pdf a mano. I miei libri sono scritti con sphinx (guarda caso), e il pdf viene generato da sphinx (attraverso il latex builder). Ora, in generale "make latexpdf" funziona e basta, se hai una catena di produzione latex nella path di sistema (pdflatex, per esempio). Ovviamente poi latex è sempre una bestia molto complicata da capire e ha un sacco di problemi (compreso un supporto unicode... particolare, diciamo). Per l'output dei miei libri faccio un sacco di piccoli accorgimenti complicati, e la catena di produzione è piuttosto complessa in realtà. Ma per le cose semplici non dovrebbe essere troppo problematico. In ogni caso, la documentazione di sphinx è sempre a portata di mano. E in ogni caso, come ho già detto, avrebbe più senso lasciar fare a uno strumento come ReadTheDocs, che fa questo di mestiere.


> Il mio script awk non azzererebbe la portabilità del lavoro ...

Sì, invece la azzererebbe proprio. Perché se in futuro qualcuno volesse partire dalla tua traduzione e aggiornarla, dovrebbe avere anche il tuo script awk non-standard... devi pensare agli scenari futuri, quando pensi alla portabilità, non al presente. Comunque, ripeto, il punto più che altro è che con awk tu dovresti comunque replicare in qualche modo (sarei tra l'altro interessato a capire come...) l'algoritmo usato da intersphinx... ma allora tanto vale usare intersphinx.... ma credo che questo nel frattempo tu l'abbia già acquisito.


> Non so se conosci awk

Sì conosco...

> Per "fuori dal sistema ufficiale di pacchettizzazione" intendo ...


Allora... chiariamo.


"Non essere root", per cominciare: questa sì che è "un'idea che la comunità linux si porta dietro da 30 anni", e del resto anche la comunità windows, e la comunità bsd, e la comunità os/2, etc etc. Tutto il resto, francamente, no.


Usare un venv non è semplicemente "un po' meglio": è il modo corretto di lavorare con Python, da parecchi anni a questa parte, su windows come su linux. Dentro un venv puoi installare pacchetti con pip o con un altro packet manager (conda, apt... a te la scelta), a seconda di quello che devi fare. Quello che invece proprio non dovresti fare, è metterti a installare pacchetti alla selvaggia (che tu lo faccia con pip o con apt) nel python di sistema.


Detto questo, ma CERTO che sphinx è anche su apt, ci mancherebbe!... ti pare che uno strumento stra-noto e stra-usato come sphinx possa non essere su apt? Sphinx è su apt, su yum, su conda, su homebrew... chi più ne ha più ne metta. https://www.sphinx-doc.org/en/master/usage/installation.html#debian-ubuntu

Quindi se vuoi installare sphinx con apt, puoi farlo senza problemi.

Ciao ad entrambi, la risposta stringata è sì, mi interessa.

Sono aperto ad ogni suggerimento, anche a resettare tutto quello che esisteva (Zanata ed affini). L'obiettivo dovrebbe essere quello di portare tutto su https://docs.python.it/ ma sono aperto a tutto ad ogni suggerimento.

Ho dimestichezza con diversi degli strumenti citati da RicPol, ecco forse un ripasso sarebbe necessario.

Colgo anche l'idea ed accetto sicuramente l'offerta che fai RicPol di coordinatore, benvenuto a bordo.

Passiamo sulla newsletter del progetto traduzione (docs) e sul gruppo Telgram dedicato se siete d'accordo.

Vi aspetto sulla newsletter e ci coordiniamo.
Daniele

Mah, sì... Intanto vedo che l'OP ha già pubblicato la sua traduzione nel suo blog https://leucalipto.blogspot.com/ quindi in modo sostanzialmente proprietario, non mettendo a disposizione il sorgente (almeno a quanto mi risulta). E siccome vedo che ha già una "roadmap" in mente, a questo punto credo che non sia interessato a collaborare a un progetto strutturato di traduzione da ospitare qui. Ma ci dirà lui che cosa vorrà fare, nel caso.


Per quanto mi riguarda, quello che posso fare è creare un "manifesto" del progetto e metterlo sulla mailing list... diciamo con le coordinate generali di quello che si intende fare. In questo modo si può partire a discutere da una cosa concreta. Diciamo che ci penso nelle prossime serate.


Successivamente, se sono io a coordinare la cosa, potrei fare un "tutorial" (anche piuttosto dettagliato, per chi non ha proprio idea di come funzionano gli strumenti) per come si può collaborare al progetto.


Per quanto riguarda le cose tecniche... per adesso posso dire solo che:

1) "Zanata" e affini... sorry, non voglio essere uno snob e dire che se non si fa come dico io... ma il problema è che semplicemente Zanata non fa quello che vogliamo noi. Zanata serve quando devi tradurre un documento in 10 lingue, ed è basato su Gettext (o cose analoghe). Inoltre ha un suo concetto di versioning, ma non è lo stesso di Git. Inoltre non supporta nativamente RestructuredText. Ora, qui il problema è che noi dobbiamo
- fare il tracking di una repo Git
- che ha diversi branch
- i cui documenti sono scritti in RestructuredText
- e dobbiamo tradurre in una lingua sola.
Per tutto questo, Zanata non è lo strumento che viene naturale usare. Non sono io che mi incaponisco a volere Git e Sphinx. Il problema è che LA DOC DI PYTHON originale usa Git e Sphinx. E questo è un fatto che non possiamo cambiare. Quindi, tutto ciò che si allontana da Git e Sphinx richiede un "layer" di lavoro in più che onestamente non me la sentirei di progettare.


2) Penso anche io che la cosa migliore sarebbe mantenere la repository della traduzione "a casa" di python.it. Fisicamente, credo che la cosa migliore sarebbe fare il "lavoro sporco" sulla mia repository e fare un clone sul GitHub di python.it dove fare push periodici. La repo su python.it sarebbe quella "ufficiale", con pochi commit.


3) L'output html ottenuto con Sphinx si potrebbe senz'altro pubblicare su python.it, non c'è problema. La cosa ottimale sarebbe fare qualche hook GitHub per aggiornare il risultato pubblicato ogni volta che viene fatto un push sulla repository "ufficiale", ma se non si riesce ad automatizzare la cosa, si può benissimo anche fare tutto a mano... non prevedo comunque un traffico gigantesco. Ovviamente, se pubblichiamo su python.it, allora eliminerei la mia attuale pubblicazione su ReadTheDocs.


E questo è tutto quello mi viene in mente per il momento... ma prometto che scrivo qualcosa di più dettagliato per la mailing list.

Grazie della risposta RicPol, diciamo che sono aperto ad ogni possibilità e non ho preconcetti.

Ho dimestichezza con un altro flusso di lavoro basato su Zanata, ma chi se ne frega, sono pronto a leggere quello proponi ed imparare quello che non so.

Alla fine interessa il risultato, certo è che se dobbiamo mettere in piedi il sistema per me e per te senza nessun altro collaboratore non è l'ideale, ma diciamo che prepariamo il terreno per altre collaborazioni.

A questo punto aspetto un messaggio sulla newsletter.

Cya

ciao, ho finito il tutorial su argparse, ecco il link:

https://leucalipto.blogspot.com/2020/09/argparse-tutorial.html

se vedete degli errori fatemi un fischio.

Torno da un periodo di lavoro complicato che non mi ha lasciato tempo di respirare, e vedo che il mio piano di lavoro per tradurre la documentazione, pubblicato sulla mailing list all'inizio di settembre, non è stato preso in considerazione da nessuno... come mi aspettavo ampiamente e come sotto sotto mi auguravo ;-)

Per me direi che questo chiude la questione.


Vuol dire che avrò più tempo per aggiornare/finire i miei due libri... quello su python e windows aspetta da mesi un capitolo nuovo... inoltre tra qualche giorno esce python 3.9, quindi dovrò fare un bel po' di piccoli aggiornamenti... Direi che le cose da fare non mi mancano.


Nel frattempo la mia traduzione del tutorial resta lì, aggiornatissima, multi-versione, open source e disponibile a tutti... Se qualcuno ha voglia di partire da lì, mi faccia un fischio!

No, non è assolutamente così, ma hai ragione in pieno, non ti avevo più risposto anche se mi ero riproposto di farlo.

Purtroppo sto attraversando delle problematiche personali piuttosto pesanti, ma il tuo discorso è molto interessante. Confesso di non aver capito tutti i passaggi, alcuni mi sono ostici per non dire oscuri, anche perché non li ho mai affrontati, ma in fin dei conti non mi spaventano.

Se gli altri non hanno risposto questo non mi riguarda, resto molto interessato, anche se in questo momento storico non posso dedicarci nulla, come ad ogni altro progetto in cui ero/sono coinvolto. Il discorso per me resta aperto, poi capisco se qualcuno degli attori coinvolti nel frattempo "si scoccia", col tempo me ne farò una ragione.

Ciao e grazie della disponibilità.