italia / docs.italia.it Goto Github PK

Details

Se provo a importare un documento con lo stesso titolo (per la precisione, lo stesso name nel document_settings.yml) di uno esistente, ottengo il seguente errore:

Questo significa che due comuni diversi, per esempio, non possono avere entrambi un documento chiamato "Circolare FOIA". È il comportamento che vogliamo ottenere?

Dettagli

Un repo cancellato dall'organizzazione GitHub appare ancora fra i documenti importabili su Docs Italia.
In particolare, il repo siti-web-scuole-docs appare ancora fra i repo disponibili per l'importazione, anche se quel repo è stato rimosso. Se si prova a importare il documento, si ottiene l'errore "nessun document_settings disponibile".

Risultato che ci si aspettava

Rimuovere il repo dall'organizzazione dovrebbe automaticamente cancellare il documento da Docs Italia?

Details

Problema con la gestione dei documenti già presenti su Docs Italia per gli utenti con privilegi normali.

Expected Result

Un membro di un'organizzazione dovrebbe vedere come già presenti su Docs Italia i documenti già compilati della stessa organizzazione.

Actual Result

Attualmente, l'utente vede il pulsante "Importa" invece che il collegamento al documento già presente.
Cliccando sul pulsante, si ottiene il seguente messaggio di errore:

Mentre dovrebbe vedersi:
https://docs-italia-staging.teamdigitale.it/citta-metropolitana-amba-raba/popolazione-del-comune/altra-anagrafe-docs/it/bozza/

Nel caso di un documento in cui il file conf.py non si trova nella root del repo (ad esempio 18app-esercenti-docs), i dati del file document_settings.yml non arrivano al build context.
Questo accade perché il codice che aggiungiamo al conf.py assume che il file document_settings.yml si trovi nella stessa directory.

Questo causa il fallimento della compilazione perché il tema assume che i metadati del documento siano sempre presenti nel context della build.

A valle del fix di questo bug, penso sia utile uniformare la struttura di tutti i repo dei documenti seguendo lo schema che suggerivo qui.
Questa considerazione vale solo per i nuovi documenti perché la struttura del repo impatta sullo schema degli URL generati, quindi eventuali modifiche a documenti esistenti implicherebbero la creazione di un sistema di redirect interno che al momento aggiungerebbe solo entropia e mal di testa.

cc @francescozaia

Details

Supponiamo che l'organizzazione su GitHub Acme sia autorizzata su Docs Italia.
Tutti i repo di Acme diventano a quel punto automaticamente pubblicabili su Docs Italia.
È possibile prevenire la pubblicazione di un documento da parte di Acme, qualora questo non abbia le caratteristiche per stare su Docs Italia?

Expected Result

Vorrei che ci fosse un meccanismo di controllo dei documenti pubblicati che serva non da barriera a monte, ma che permetta di "spubblicare" eventuali documenti non consoni alla piattaforma. È previsto? In caso contrario, parliamone :)

@pablopers riporta un errore del filtro bold-headers applicato a questo documento https://github.com/pablopers/ISTATRapportoannuale2018. L'errore è:

pandoc: Cannot decode byte '\x97': Data.Text.Encoding.Fusion.streamUtf8: Invalid UTF-8 stream

Dettagli

Escludere dall'endpoint docsitalia/api/document/[project-slug]/active_versions/ le versioni private. I motivi sono due:

• la versione non è più così "privata"
• la versione appare nel menu a tendina di tutte le versioni del documento

Dettagli

• Pagina web del progetto su Docs Italia: https://docs-italia-staging.teamdigitale.it/projects/tags/linee-guida/

Risultato che ci si aspettava

Visualizzare tutti i documenti con uno specifico tag.

Risultato effettivo

Accanto ad ogni documento è mostrato il nome dell'utente proprietario linkato alla pagina del profilo corrispondente. Penso che i nomi dei proprietari dei documenti non debbano essere mostrati né linkati.
Nice to have: si potrebbero linkare il progetto e il publisher di appartenenza di ciascun documento.

Dettagli

Quando si creano documenti da repo che non hanno il conf.py (che in futuro sarà la regola), il codice di docs italia cerca il master_doc (che normalmente è il file index.rst) usando una funzione che a sua volta fa un'altra chiamata per sapere in quale directory cercare il master_doc.
La funzione docs_dir effettua una ricerca, a partire dalla root del repo del documento, di nomi di subdirectory contenuti in una lista predefinita (['docs', 'doc', 'Doc', 'book']). Succede quindi che, se una di queste subdirectory esiste, diventa il valore della variabile docs_dir.
La funzione chiamante create_index cerca quindi il master_doc nella directory docs_dir e, se non lo trova, ne genera uno (che è semplicemente un placeholder definito staticamente nel codice).
Il bug sta nel fatto che, se non esiste il conf.py ed esiste un directory tra quelle definite nella lista, allora il file index.rst che dovesse trovarsi nella root del repo viene ignorato.

Questo è il caso del repo https://github.com/docs-theme-org/design-docs-test che è un fork del repo https://github.com/italia/design-docs privato del suo conf.py.

Il risultato della build è: https://docs-italia-staging.teamdigitale.it/docs-theme-org/progetto-tema/design-docs-test/it/bozza/.

Propongo una PR che vincoli la variabile docs_dir alla sola root del repo del documento. Questo è anche coerente con la strutturazione dei repo per i documenti di Docs Italia che abbiamo indicato nella guida.

Details

I documenti impostati su "Private" danno un errore 404.

Expected Result

Se sono il proprietario del progetto, dovrei essere in grado di vedere un documento privato.

Dettagli

Da https://w1.docs.iast.it/ non è visibile la documentazione https://w1.docs.iast.it/italia/data-analytics-framework/pianotri-elencobasidatichiave/it/bozza/ (che va in 404 come descritto in #164), ma entrando nella pagina del singolo progetto https://w1.docs.iast.it/italia/daf/ la documentazione compare (Elenco basi di dati chiave).

Risultato che ci si aspettava

La documentazione "Elenco basi di dati chiave" non dovrebbe mai comparire.

Risultato effettivo

La documentazione "Elenco basi di dati chiave" è raggiungibile dalla pagina https://w1.docs.iast.it/italia/daf/ o cercando "Elenco basi di dati chiave", e possibilmente in altri modi.

Il codice di Analytics è lo stesso su staging e produzione.
Da verificare perché nell'ambiente di produzione il codice di tracciamento è lo stesso di staging e non è quello che termina con -2 (qui il codice per dettagli).

Dettagli

L'eliminazione del publisher elimina a cascata anche il publisher_project e tutti i documenti funzionalità aggiunta con questa PR.
Al vecchio URL le documentazioni risultano ancora disponibili.
Inoltre all'eliminazione del publisher non consegue anche l'eliminazione della corrispettiva "Remote organization" che quindi continua ad apparire nel frontend tra quelle abilitate all'importazione di documenti.

Risultato che ci si aspettava

Ai vecchi URL dovrebbe essere restituito un 404.
L'organizzazione GitHub non dovrebbe apparire tra quelle abilitate all'importazione.

Risultato effettivo

Le documentazioni risultano ancora disponibili e l'organizzazione è elencata nella pagina di importazione dei nuovi documenti.

Dettagli

Da https://w1.docs.iast.it/, cliccando sul progetto "Data & Analytics Framework", a volte porta correttamente su https://w1.docs.iast.it/italia/daf/, altre porta su https://w1.docs.iast.it/italia/data-analytics-framework/ che non è corretto. Avviene anche per la documentazione "Regole tecniche" di SPID, il cui progetto linka a https://w1.docs.iast.it/italia/sistema-pubblico-di-identita-digitale/ anziché https://w1.docs.iast.it/italia/spid/.

A naso, sembra sia stato introdotto un errore di recente perché le documentazioni importate la scorsa settimana sono ok, mentre le nuove no.

Questo disallineamento avviene anche nelle pagine delle singole amministrazioni (es: https://w1.docs.iast.it/italia/daf/).

Risultato che ci si aspettava

Tutti i link ai progetti devono portare alla pagina corretta.

Risultato effettivo

Alcuni link ai progetti non portano alla pagina corretta; non mi è chiaro da dove arrivino quegli slug errati, come ad esempio:
data-analytics-framework anziché daf
sistema-pubblico-di-identita-digitale anziché spid

Da usare al posto di quello di default

Non so se è quello che vogliamo. E visto che ci siamo deve anche gestire meglio gli errori:

Traceback (most recent call last):
  File "/home/docs/docs.italia.it/readthedocs/projects/tasks.py", line 313, in run
    self.version = self.get_version(self.project, version_pk)
  File "/home/docs/docs.italia.it/readthedocs/projects/tasks.py", line 84, in get_version
    version_data = api_v2.version(version_pk).get()
  File "/home/docs/virtualenv/lib/python3.5/site-packages/slumber/__init__.py", line 155, in get
    resp = self._request("GET", params=kwargs)
  File "/home/docs/virtualenv/lib/python3.5/site-packages/slumber/__init__.py", line 101, in _request
    raise exception_class("Client Error %s: %s" % (resp.status_code, url), response=resp, content=resp.content)
slumber.exceptions.HttpNotFoundError: Client Error 404: http://localhost:8002/api/v2/version/868/

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "manage.py", line 11, in <module>
    execute_from_command_line(sys.argv)
  File "/home/docs/virtualenv/lib/python3.5/site-packages/django/core/management/__init__.py", line 353, in execute_from_command_line
    utility.execute()
  File "/home/docs/virtualenv/lib/python3.5/site-packages/django/core/management/__init__.py", line 345, in execute
    self.fetch_command(subcommand).run_from_argv(self.argv)
  File "/home/docs/virtualenv/lib/python3.5/site-packages/django/core/management/base.py", line 348, in run_from_argv
    self.execute(*args, **cmd_options)
  File "/home/docs/virtualenv/lib/python3.5/site-packages/django/core/management/base.py", line 399, in execute
    output = self.handle(*args, **options)
  File "/home/docs/docs.italia.it/readthedocs/docsitalia/management/commands/rebuild_projects.py", line 33, in handle
    task.run(version.project.pk, version_pk=version.pk, build_pk=build.pk)
  File "/home/docs/docs.italia.it/readthedocs/projects/tasks.py", line 332, in run
    build_id=build_pk,
AttributeError: 'UpdateDocsTaskStep' object has no attribute 'setup_env'

Details

Il template delle email (/templates/core/email/base.html) fa riferimento a RTD nei testi e nelle immagini.

Expected Result

Dovrebbe avere lo stile di Docs Italia (da definire).

Dettagli

Al momento, la ricerca torna tra i risultati anche documenti che sono stati rimossi (design-docs), i cui link ovviamente non funzionano. Penso si tratti solo di cache ES, per cui dovremmo assicurarci di ripulire eventuali disallineamenti.

Dettagli

Le pagina delle singole "Amministrazioni" (ad esempio https://docs.italia.it/italia/ e https://docs.italia.it/AgID/) sono al momento una copia della vista del singolo "Progetto" (es https://docs.italia.it/italia/pagopa/).

Essa dovrebbe essere invece molto più simile a quanto visibile nei layout, magari migliorandola utilizzando loghi e contenuti presenti nel file yaml*, e sicuramente con:

• numero di documenti contenuti
• link esterno all'amministrazione se presente

*i dati disponibili per ogni Amministrazione dovrebbero essere già disponibili in pagina, e arrivano da un file YAML importato da Python, ad esempio https://github.com/italia/italia-conf/blob/master/publisher_settings.yml e https://github.com/AgID/italia-conf/blob/master/publisher_settings.yml.

Dettagli

La card del progetto con titoli troppo lunghi va in overflow.
Succede nella home page e nelle pagine di dettaglio di publisher projects

Risultato che ci si aspettava

Un truncatewords sui titoli troppo lunghi.

Risultato effettivo

I titoli troppo lunghi vanno in overflow

La variabile versions nel build context è definita in nel file conf.py.tmpl. Questa è una lista delle versioni da usare per il menu che permette di passare da una versione all'altra di un documento.
La lista è costruita usando la variabile versions (stesso nome) che proviene dall'istruzione di compilazione del template che ricava la variabile da questa istruzione.
Infine, il codice che restituisce le versioni attive di un documento è richiamato dal modello project, che sembra correttamente impostare un filtro sullo stato della versione built=True.

Il bug è osservabile nel documento: https://docs-italia-staging.teamdigitale.it/docs-theme-org/progetto-tema/design-docs-test/it/bozza/ per il quale, nel menu a tendina, appare anche la versione "stabile" che, in realtà non è buildata.
Anche un'interrogazione via api mostra che per la versione "stabile", la variabile built è impostata su false: https://docs-italia-staging.teamdigitale.it/docsitalia/api/document/design-docs-test/active_versions/
Nel log della build, all'istruzione che mostra il conf.py generato, invece si legge:

'versions': [
    ("bozza", "/docs-theme-org/progetto-tema/design-docs-test/it/bozza/"),
    ("stabile", "/docs-theme-org/progetto-tema/design-docs-test/it/stabile/"),
    ],

Details

Nella homepage di Staging, ci sono un paio di immagini che tornano un 404 (Not Found):

https://docs-italia-staging.teamdigitale.it/media/static/projects/images/book-bg.png
https://docs-italia-staging.teamdigitale.it/media/static/projects/images/documents-bg.png

Quei file in effetti non sono presenti tra i sorgenti della cartella media, ma in teoria ad un certo punto un collectstatic dovrebbe copiarcele da https://github.com/italia/docs.italia.it/tree/italia-2.3.13/readthedocs/projects/static/projects/images, dove sono presenti.
In locale perlomeno funziona così.

Dettagli

Questo il messaggio di errore, che sembra abbastanza esplicativo:

Running Sphinx v1.7.4
WARNING: the config value 'settings_project_name' is set to a string with non-ASCII characters; this can lead to Unicode errors occurring. Please use Unicode strings, e.g. u'Content'.
WARNING: the config value 'project' is set to a string with non-ASCII characters; this can lead to Unicode errors occurring. Please use Unicode strings, e.g. u'Content'.
loading translations [it]... done
making output directory...

Traceback (most recent call last):
  File "/home/docs/docs.italia.it/user_builds/lg-modellointeroperabilita-docs/envs/bozza/local/lib/python2.7/site-packages/sphinx/cmdline.py", line 303, in main
    args.warningiserror, args.tags, args.verbosity, args.jobs)
  File "/home/docs/docs.italia.it/user_builds/lg-modellointeroperabilita-docs/envs/bozza/local/lib/python2.7/site-packages/sphinx/application.py", line 227, in __init__
    self.config.check_types()
  File "/home/docs/docs.italia.it/user_builds/lg-modellointeroperabilita-docs/envs/bozza/local/lib/python2.7/site-packages/sphinx/config.py", line 204, in check_types
    default = default(self)  # could invoke l_()
  File "/home/docs/docs.italia.it/user_builds/lg-modellointeroperabilita-docs/envs/bozza/local/lib/python2.7/site-packages/sphinx/builders/html.py", line 1428, in <lambda>
    lambda self: l_('%s %s documentation') % (self.project, self.release),
  File "/home/docs/docs.italia.it/user_builds/lg-modellointeroperabilita-docs/envs/bozza/local/lib/python2.7/site-packages/sphinx/locale/__init__.py", line 110, in __mod__
    return self.data % other
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 38: ordinal not in range(128)

Encoding error:
'ascii' codec can't decode byte 0xc3 in position 38: ordinal not in range(128)
The full traceback has been saved in /tmp/sphinx-err-panQ9r.log, if you want to report the issue to the developers.

Per ora ho aggiunto @yakky tra i gestori; @paoloromolini non ho trovato un utente che apparentemente afferisse a te... fammi sapere se vuoi accesso al documento come gestore.

Dettagli

Lo scrivo giusto come reminder, anche se credo sia già stato risolto e debba solo essere deployato in produzione: ogni nuovo documento importato (che è in stato private by default), non permette al publisher stesso di essere visionato. È necessario agire sulla tendina dedicata e renderlo public per poterlo vedere; questo ovviamente ha il side-effect di rendere il documento disponibile a tutti.

Risultato che ci si aspettava

Anche i documenti in stato private devono essere visibili ai gestori del documento stesso.

Risultato effettivo

I documenti in stato private vanno in 404.

Dettagli

Nella homepage e nella pagina "cos'è docs italia" ci sono alcuni riferimenti a documenti di esempio, che al momento sono su RTD. Vanno modificati i link affinché essi siano collegati a documenti hostati su Docs Italia.

Details

https://docs-italia-staging.teamdigitale.it/projects/cad-docs/builds/737/

Actual Result

La compilazione del PDF si blocca.
Se interpreto bene il log, sembra che ci sia un problema con il titolo del documento. Mi pare il colpevole sia l'apostrofo in dell'amministrazione.

Details

Appena registrati, la pagina dashboard è titolata "Ready to share your documentation?", ma dovrebbe essere in italiano.

Nel codice sembra essere ok, e su Transifex la traduzione sembra essere corretta ("Pronti per condividere la tua documentazione").

Expected Result

Il testo dovrebbe essere in italiano

Actual Result

Il testo è in inglese

Dettagli

Al momento, la struttura dell'URL è del tipo: org/proj/nome-repository.
Secondo me avere nome-repository lì non è ideale, visto che molti repo nell'organizzazione Italia hanno nomi in inglese.

Proposta

Si potrebbe usare il parametro short_name, già previsto nel document_settings.yml, per costruire l'URL del documento. A quel punto, short_name diventerebbe obbligatorio e non più opzionale.

Si potrebbe poi pensare di estendere lo stesso meccanismo a organizzazione e progetti, in modo da uniformare la creazione degli URL.

Details

In the JSON returned by https://docs-italia-staging.teamdigitale.it/docsitalia/api/document/ the field results.[].publisher.name is always an empty string.

Expected Result

publisher.name should contain the publisher name

Actual Result

publisher.name is always an empty string.

Details

• Read the Docs project URL: dashboard
• Build URL (if applicable):
• Read the Docs username (if applicable): https://w1.docs.iast.it/profiles/danse/

Actual Result

The style sheet has a quirk

Questo è il risultato della prima conversione del documento "Guida tecnica all’uso di metriche per il software applicativo sviluppato per conto delle pubbliche amministrazioni".

Guida-tecnica.zip

Dettagli

Verificare il readme dei role ansible per documentare alcuni comandi operativi per:

• Fare il deployment degli aggiornamenti "standard" di RTD su staging e produzione
• Fare il deployment degli aggiornamenti del convertitore su staging e produzione
• Fare il deployment di branch specifici di RTD su staging e produzione

Stemma Amministrazioni

• è possibile visualizzare lo stemma della propria amministrazione?

• è corretto inserire lo stemma all'inizio di ogni documento?

• è ancora utile avere per ogni repo una cartella /assets/images contenente il file dello stemma richiamato nel file conf.py (dato che il conf.py dovrebbe sparire)?

• Github project URL: https://github.com/cittametropolitananapoli/statuto-cmna-docs*

• Docs Italia project URL (staging): https://docs-italia-staging.teamdigitale.it/cittametropolitananapoli/statuto-cmna/statuto-cmna-docs/it/master/*

Expected Result

1)Stemma accanto al nome dell'amministrazione nella sezione "Amministrazioni"
2)Stemma all'inizio di ogni documento

Actual Result

• lo stemma è visibile all'inizio del documento solo se inserito come immagine nel contenuto del documento*

Details

Filtering by project slug returns an empty set in https://docs-italia-staging.teamdigitale.it/docsitalia/api/document/?project={project slug}

Expected Result

The project identified by the given slug.

Actual Result

An empty set is returned.

Dettagli

Prevedere la possibilità di avere un lancio in homepage sulla falsariga di quanto c'è ora online:

Quando sarà rilasciato il nuovo tema per Docs Italia bisognerà modificare il nome del package python da docs-italia-theme a docs_italia_theme.
Il codice da modificare è quello introdotto nella #47.

La pagina di registrazione utente dovrebbe avere più informazioni per l'utente, con link alla Guida per la pubblicazione e con i vantaggi della registrazione. Anche la pagina di Login e di recupero Password andrebbero ripulite un po'.

Anche l'email di recupero password è da rivedere:

Il link di re-impostazione della password non è più valido, non perdete tempo a copiarlo. 🙈

Dettagli

La compilazione di questo documento fallisce: https://docs-italia-staging.teamdigitale.it/projects/cie-middleware-windows-docs/builds/1153/

L'errore è:

Encoding error:
'ascii' codec can't decode byte 0xc3 in position 16: ordinal not in range(128)

Dettagli

Per mantenere un migliore controllo sulle documentazioni, vorremmo attivare un canale Slack che notifichi ogni build di nuovi documenti.

Creazione di una pagina "Amministrazioni" (che in futuro diventerà questa), che listi tutte le amministrazioni con documentazioni attive.

Se nei metadata cambia lo slug di un progetto viene creato un nuovo PublisherProject. Quindi vengono disabilitati i PublisherProject che non hanno più uno slug nei metadati del publisher. Dobbiamo però ricordarci di spostare i documenti (Project) associati a questi PublisherProject altrimenti le organizzazioni spariscono dal sito i nuovi progetti non hanno documentazioni associate.

Dettagli

Come da schermata allegata:

Verificato sia su staging che su produzione.

Risultato che ci si aspettava

Un'immagine che identifichi il sito da cui arriva l'email.

Risultato effettivo

Manca l'immagine.

EPIC

Ci siamo scontrati con la difficoltà di avere la versione tradotta di un documento, al momento alcuni documenti tradotti sono completamente scollegati tra loro:

• https://docs.italia.it/italia/developers-italia/lg-acquisizione-e-riuso-software-per-pa-docs/it/stabile/
• https://docs.italia.it/italia/developers-italia/gl-acquisition-and-reuse-software-for-pa-docs/en/stabile/

oppure

• https://docs.italia.it/italia/developers-italia/publiccodeyml/it/master/
• https://docs.italia.it/italia/developers-italia/publiccodeyml-en/en/master/

Per il piano triennale si è riusciti ad avere entrambe allo stesso URL, ma non mi è chiaro perché le versioni non sono allineate.

• https://docs.italia.it/italia/piano-triennale-ict/pianotriennale-ict-doc/it/2019-2021/
• https://docs.italia.it/italia/piano-triennale-ict/pianotriennale-ict-doc/en/stabile/

Sicuramente è necessario il ripristino dell'opzione "Translations" sotto le "Impostazioni Avanzate" per i publisher, che permette di collegare due documenti in lingue diverse.

Sarà inoltre necessario verificare che si riesca a switchare tra una lingua e l'altra semplicemente cambiando il locale nell'URL.

It's incomplete and in some cases as in the search button very confusing:

https://www.transifex.com/readthedocs/readthedocs/

Dettagli

Al momento i documenti in homepage sono mostrati semplicemente in base alla compilazione più recente. Alcuni documenti di fondamentale importanza, come il CAD, le Linee Guida di Design ed altro sarebbe bene fossero portati sempre in alto.

Per ora, con ispirazione ai layout, si potrebbero mostrare 8 documenti curati "a mano", seguiti dai più recenti identificati da opportune titolazioni.

"Se non ti sei registrato per un account su Read the Docs, puoi non considerare questa email."

cercando ipsum per esempio tornano progetti che non dovrebbero essere indicizzati perchè o non hanno il publisher o non hanno documentazione buildata (l'url alla documentazione torna 404).

Details

Ho provato ad importare un paio di documenti nell'ambiente di pre-produzione:

• https://github.com/italia/anpr
• https://github.com/italia/daf-piano-di-sviluppo

Per entrambi ho avuto lo stesso errore riguardo invalid document_settings.yml, molto probabilmente a ragione. Nel primo caso il file non c'è, nel secondo c'è ma forse non era formattato correttamente (ho creato una PR italia/daf-piano-di-sviluppo#10 per sistemarlo).

Detto questo, ora vedo i due progetti in uno stato "inconsistente":

Che si traduce in questa schermata se provo a cliccare su uno dei due:

In attesa dell'approvazione della PR (e quindi ad avere un file document_settings.yml corretto), mi domandavo se poi riuscirò a compilare quei documenti.

Details

Su Transifex sono presenti le traduzioni in Italiano per tutti i testi previsti.
Penso sia sufficiente scaricare da Transifex il file for_use_readthedocs_readthedocs_it.po e sostituirlo a questo file.

Alcuni riferimenti utili: la documentazione di RTD sull'i18n.

Expected Result

Tutti i testi dovranno essere tradotti in Italiano.

Actual Result

Alcuni testi sono in inglese.