italia / docs-italia-theme

Tema per i documenti pubblicati su Docs Italia

Docs Italia theme

This is the official theme for any piece of documentation hosted on the upcoming Docs Italia.

How to use Sphinx Italia on your documentation

• Add the following line to your documentation requirements.txt file:

  $ pip install git+https://github.com/italia/docs-italia-theme.git
  

• In your conf.py file, you'll need to specify the theme as follows:

  # Add this line at the top of the file within the "import" section
  import docs_italia_theme
  
  # Add the Sphinx extension 'docs_italia_theme' in the extensions list
  extensions = [
    # ...,
    'docs_italia_theme'
  ]
  
  # Edit these lines
  html_theme = "docs_italia_theme"
  html_theme_path = [docs_italia_theme.get_html_theme_path()]
  

Contributing or modifying the theme

• Clone the repository:

  git clone git+https://github.com/italia/docs-italia-theme.git
  

• If needed, install Sphinx into a virtual environment:

  pip install sphinx
  

• If needed, install SASS:

  gem install sass
  

4. Install node.js and grunt:

   // Install node on OS X
   brew install node
   
   // Install grunt
   npm install -g grunt-cli
   
   // Now that everything is installed, let's install the theme dependecies.
   npm install
   

5. Run the main script to load a sample docs with the Sphinx Italia theme applied:

   npm start
   

   This will compile static assets and watch files required for the theme to reload at runtime.

TODO: building a release, handling versioning system to enable automatic update on Docs Italia platform

docs-italia-theme's Issues

Output pdf single/twoside

I pdf generati dai documenti di Docs Italia hanno tutti il layout twoside di Latex.
Questo layout è ottimizzato per la stampa: una delle caratteristiche principali è la presenza di pagine bianche prima di ogni capitolo, che fanno in modo che l'inizio del capitolo capiti sempre su una pagina dispari.

Da un lato questo potrebbe essere un bene, dall'altro potrebbe dare fastidio quando si cerca di leggere il pdf sullo schermo (in realtà questo è il comportamento che stiamo cercando di sradicare con Docs Italia...).

Vorrei avere le vostre opinioni al riguardo, che ne pensate?

I titoli in h5 non hanno uno stile

Come si può vedere da screenshot ( http://design-italia.readthedocs.io/it/latest/doc/user-research/usabilita.html#quanti-e-quali-tipologie-di-partecipanti-selezionare) ai titoli in h5 non viene applicato uno stile. Mi sembra solo vengano resi con una dimensione maggiore.

conf.py snippet is not enough to use this theme

README instructs users to add the following lines to the project's conf.py:

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

However this only applies to local builds, while RTD builds lack the <link> tags for the theme stylesheets. It looks like the following code is needed as well (see the design-doc conf.py):

if not on_rtd:  # only import and set the theme if we're building docs locally
    html_theme = 'sphinx_italia_theme'
    html_theme_path = ["_themes", ]
else:
    # Override default css to get a larger width for ReadTheDoc build
    html_context = {
        'css_files': [
            '_static/css/theme.css',
            '_static/css/custom.css',
        ],
    }

A sample conf.py should be included in this repository (like in the newer https://github.com/italia/docs-italia-theme) and/or the README should be updated.

Leggibilità font bold

Con il nuovo tema ho riscontrato, in alcuni casi, un problema di leggibilità del font in bold (nello screen ad esempio vedi "Top motori di ricerca referenti" e altri titoletti a seguire).

Applicazione tema alla pagina 404

Quando si segue un link che punta ad una pagina non (più) esistente, appare una pagina 404 intitolata "Trovato Labirinto", con il tema standard di ReadTheDocs ed un bottone "Apri Sessione" che punta alla pagina di login di RTD.

Esempio: http://test-pianotriennale-ict.readthedocs.io/it/docs-italia-theme/doc/foobar.html

Non so se RTD permetta di personalizzare le pagine 404, ma se possibile mi sembra utile farlo.

Syntax error on a .sass file breaking build

This code is preventing the sass build to succeed.

Permalink a latest

Nel CAD non c'è una versione "latest" e quindi non c'è modo di avere un permalink alla versione più recente, con il risultato che tutti i link in ingresso a questa documentazione punteranno ad una versione storica in caso di aggiornamenti - a meno che l'utente non sia sufficientemente furbo da copiare l'URL della root senza path.

Questa cosa forse si può gestire dando delle linee guida su come creare i tag nei repository (ad esempio: deve esserci sempre un tag latest?) oppure con della logica nel tema?

Update the README file

The README file was not updated to mention sphinx_italia_theme.

Segnalazioni su invision

https://projects.invisionapp.com/share/BSCQ82BKD#/screens/255791818/comments

Altezza fissa del link alle versioni statiche del testo

propongo di levare 100px di altezza all'elemento fixed della navbar che attualmente occupa più spazio di quel che potrebbe:

docs-italia-theme/sass/badge_only.sass

Line 96 in b26ac5a

height: 100px

Tendina cambio versione

Mi sembra che la tendina per il cambio della versione non funzioni correttamente, credo vada modificata aggiungendo i riferimenti a publisher e progetto corrente.

Il comportamento è visibile a questo (bellissimo) documento: https://w1.docs.iast.it/italia/designers-italia/design-docs/it/bozza/

Sono ovviamente a disposizione per test ecc.

Edit: (un altra cosa minor) per nomi di versione lunghi, la tendina va a capo, è forse meglio croppare un certo numero di caratteri?

Note al documento

Le note al documento non sono generalmente visibili. Per vederle, bisogna cliccare su una nota nel testo e aprire in questo modo la sezione.

Vogliamo aggiungere un link al titolo ("Note al paragrafo x.y") per fare in modo che la sezione risulti visibile?

Link a tabelle e figure non allineato col testo

I link a tabelle e figure non sono allineati con il resto del testo. Ecco un esempio:

Problemi con il footer

Il footer dei documenti con il nuovo tema non appare correttamente.

comportamento menù/indice

Usando la documentazione ho incontrando un problema che è particolarmente fastidioso soprattutto quando consulti velocemente il documento passando da un paragrafo all’altro.
Quando clicchi su un paragrafo, il menù di sinistra correttamente apre l’accordion in cui quel paragrafo è contenuto (il blocco diventa grigio). Ma non riposiziona il menù portando quel blocco grigio in alto. Il risultato è che la posizione del blocco grigio è variabile (te lo puoi trovare in alto o in basso) e addirittura potresti non vederla, se il menù è molto lungo potresti dover usare la barra di scorrimento per vederla
Qui l’esempio
http://design-italia.readthedocs.io/it/stable/doc/service-design/accessibilita.html#un-esempio-per-capire-uso-del-colore
Forse nel nuovo tema il comportamento è un po' diverso ma lo stesso problema si ripresenta
http://cloud-pa.readthedocs.io/it/latest/circolari/SaaS/circolare_docs/articolo-7.html
Credo che un comportamento corretto sarebbe posizionare il blocco grigio in alto, lasciando intravere una riga del menù nero sopra per far capire che il menù continua sopra più o meno così

Supporto multilingua

Il tema deve poter supportare la visualizzazione di documentazione anche in inglese.
Un primo caso di applicazione è Three-Year Plan for ICT in Public Administration 2017 - 2019.

Pagine non responsive

Riporto una issue segnalata da @pablopers.

• Alcune volte le pagine non vengono visualizzate correttamente su mobile (vedi, per esempio: https://docs-italia-staging.teamdigitale.it/italia/docs-italia/docs-italia-guide/it/bozza/index/pubblicare-un-documento.html)

• Le immagini vengono ridotte senza mantenere l'aspect ratio, creando una distorsione innaturale.

Lunghezza eccessiva delle righe di testo

Imposterei un max-width a 40em per paragrafi, titoli e liste

Link non funzionanti

A volte i link esterni non funzionano, anche se formalmente corretti in RST.

Vedi ad esempio: https://docs-italia-staging.teamdigitale.it/italia/18app/18app-esercenti-docs/it/bozza/faq-esercenti.html#non-ho-mai-emesso-fatture-elettroniche-posso-comunque-aderire-all-iniziativa-o-devo-dotarmi-necessariamente-di-alcuni-strumenti

Riquadri di admonition personalizzati

I riquadri di admonition personalizzati (quelli ottenuti con .. admonition:: ) hanno un rientro diverso rispetto al resto del testo.

Comportamento suggerito: dovrebbero avere rientri e larghezza uguali a quelli dei box predefiniti.

Esempio: http://admo.readthedocs.io/it/latest/

Vedi anche: #32

Elenchi di secondo livello

Gli elenchi di secondo livello (che tra l'altro sconsigliamo di usare) hanno un simbolo strano: sembra un cerchio sovrapposto a un triangolo.

Vedi per esempio: https://docs-italia-staging.teamdigitale.it/italia/docs-italia/docs-italia-guide/it/bozza/index/che-cos-e-docs-italia.html#nuove-funzionalita

Link al diff tra versioni

Sarebbe utile generare link diretti alla pagina /compare offerta da GitHub per vedere le differenze tra le versioni.

Ad esempio:
italia/cad-docs@v2016-08-26...v2017-12-13

Mi sembra che non si possa limitare il diff ad un singolo file.

Altezza minima per la regione content

Quando la regione content ha pochi contenuti, il layout della pagina risulta eccessivamente collassato.
Esempio: https://censimentoict.italia.it/it/latest/

"Modifica su GitHub" vs "Vedi su GitHub"

Mi sembra che nel precedente tema ci fosse la possibilità di trasformare il bottone "Modifica su GitHub" in "Vedi su GitHub" per quei repository che non sono orientati alla modifica collaborativa (ad esempio il Piano Triennale o il CAD). Nel nuovo tema mi pare che questa possibilità non ci sia, o perlomeno non la trovo documentata e non è applicata nei due casi sopra citati.
È stato scelto di mantenere sempre "Modifica"?

Parametro collapse_navigation

Vogliamo mettere questo parametro di default nel nuovo tema?

Dimensioni del testo non coerenti

Le didascalie di tabelle e figure hanno font e grandezza diversi (vedi la tabella qui: http://admo.readthedocs.io/it/latest/#id2 e la figura subito sopra).

Andrebbero probabilmente uniformate.

Esplosione build "manuale utente DAF" con tema nuovo

Sembra che e699da6 non sia sufficente:

  File "/user_builds/daf-dataportal-it-docs/envs/bozza/local/lib/python2.7/site-packages/docs_italia_theme/__init__.py", line 142, in generate_additonal_tocs
    figure_text_string = 'Fig. ' + str(figure_number[0]) + '.' + str(figure_number[1]) + ' - ' + figure_title.capitalize()
IndexError: tuple index out of range

Documentazione 18app - Le immagini vengono distorte

Alcuni immagini sul nuovo tema vengono distorte.
È possibile confrontare le due versioni:

• https://guida-18app.readthedocs.io/it/latest/linee-guida-fatturazione.html#passo-1
• https://w1.docs.iast.it/italia/18app/18app-esercenti-docs/it/bozza/linee-guida-fatturazione.html#passo-1

Volevo chiedere come procedere. Sistemiamo i sorgenti RST del documento impostando delle dimensioni (e delle descrizioni per le figure), o è da sistemare in altro modo?

Nuove versioni del tema per i documenti versionati

Al momento, la raccomandazione è di inserire git+https://github.com/italia/[email protected] nel file requirements.txt.

Cosa succede ai documenti versionati con tag quando il tema cambierà versione? Mi riferisco, per esempio, al CAD: cad.readthedocs.io.

Lo scenario è questo:

1. Creo il doc. Il requirements specifica la versione del tema 1.0beta;
2. Modifico il doc e taggo la versione 1.0;
3. Modifico il doc e taggo la versione 2.0;
4. Modifico il file requirements con il tema alla versione 1.0 release.

Quando arrivo a 4., che tema userà la documentazione? Non userà il file requirements del punto 1., e quindi il vecchio tema? Per cambiare il tema a tutte le versioni sarei costretto a fare un rebase, coi problemi che questo comporta per i tag.

Che ne pensate, @pdavide e @francescozaia ?

Traduzione del motto

Nella versione inglese del tema, il motto "Documenti pubblici, digitali." viene tradotto come "Public Documents, digital."

Propongo di modificarlo in "Public documents, made digital.", che rende meglio il significato italiano.

Pulsante di selezione delle versioni

Vorrei discutere con voi il comportamento del pulsante di selezione delle versioni.

Al momento, la versione selezionata è sempre in cima alla lista. Questo significa che le versioni più recenti del documento si trovano sotto, invece che sopra, la versione corrente. Lo trovo un po' anti-intuitivo, ma forse è solo una mia impressione.

Nel menu a tendina, mi piacerebbe invece vedere la versione corrente nella posizione in cui si trova all'interno della storia del documento. Che ne pensate?

Esempio: http://test-cad-new-theme.readthedocs.io/it/v2012-07-06/

Dare evidenza dello stato del documento

Dalla segnalazione su:
https://forum.italia.it/t/consultazioni-pubbliche-con-docs-italia-e-forum-italia/2318/3

Non è di immediata percezione per l'utente se il documento si trova in consultazione, se la consultazione è chiusa o se il documento è in versione stabile.

Leggibilità tabelle

Eliminare separatori verticali?
Eliminare sfondo alternato?

Numerazione nelle procedure

Riporto qui un possibile problema segnalatomi da @pablopers.

All'interno di una procedura, la presenza di un'immagine fa ripartire la numerazione dell'elenco. È il comportamento che ci aspettiamo?

Ecco un esempio.
Doc: https://testdig.readthedocs.io/it/latest/index/appendice-3.html#upload-tramite-interfaccia-grafica
RST: https://github.com/pablopers/docs-italia-guide/blob/master/index/appendice-3.rst

Gestione dei glossari

Al momento il glossario deve essere incluso in un unico file.

Questo causa dei problemi con la Guida al linguaggio, dove tutte le pagine di glossario non appaiono.

Qual è il modo migliore di procedere in questo caso? Modifichiamo il documento?

Formattazione admonitions

• I riquadri di admonition predefiniti si estendono oltre il corpo del testo. La barra del titolo non ha la stessa larghezza del resto del riquadro. È il comportamento previsto?

• I riquadri di admonition personalizzati (quelli ottenuti con .. admonition:: <Nome admonition> ) hanno un rientro diverso rispetto al resto del testo.

Esempio: http://admo.readthedocs.io/

Licenza e copyright nel conf.py

Nel file di configurazione conf.py (vedi, per esempio, https://github.com/italia/cloud-pa/blob/master/conf.py) sono presenti le due righe

settings_copyright_copyleft = 'Creative Commons Attribution 4.0'
settings_editor_name = 'Agenzia per l\'Italia Digitale'

Poco più sotto, però, il primo parametro appare come autore nella versione PDF:

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
  ('index', settings_file_name + '.tex', settings_project_name,
   settings_copyright_copyleft, 'manual'),
]

Problemi

1. È necessario stabilire a cosa servono quei due parametri, usando eventualmente una nomenclatura più chiara.
2. Il detentore del copyright e la licenza al momento non vengono visualizzati nella versione HTML del documento, come invece accadeva per il vecchio tema.
3. Vogliamo includere copyright e licenza nei file PDF?

Indicare un codice della versione anche per quella "latest"

Se si guarda un documento pubblicato come...
http://design-italia.readthedocs.io/it/latest/doc/introduzione-linee-guida-design.html
...se uno vuole citare una delle versioni precedenti può facilmente usare i codici 2018.1 e 2017.1
ma se uno volesse citare la versione corrente come fa? La definisce "latest al 10/05/2018"?
Potrebbe esserci un codice facilmente visibile per tutti, magari diverso
dalla codifica usate per le release di tipo "stable"?

Revisione grafica degli spazi

Ho ricevuto da più parti lamentele sul fatto che il nuovo tema abbia una distribuzione degli spazi migliorabile. Mi segnalano in particolare:

• a sinistra nel menu c'è troppo spazio sprecato
• nella parte a destra del testo, c'è molto spazio vuoto
• inoltre non vengono renderizzati bene i blocchi di codice (nel senso che il css utilizzato non è molto chiaro nel distinguere codice dal testo)

Provo a fare un passaggio a voce con @matteodesanti, nel caso commento in seguito.

Menu ripetuto

Aprendo la pagina http://test-pianotriennale-ict.readthedocs.io/it/docs-italia-theme/doc/04_infrastrutture-immateriali.html il menu a sinistra è ripetuto due volte, ovvero dopo il punto 13 ricomincia da 1 e quindi ci sono due voci "4. Infrastrutture immateriali" con tutte le loro sottopagine.

Gestione dei documenti multilingua

Al momento, sembra che non ci sia un pulsante per cambiare la lingua di un documento.

Esempio.
ITA: http://admo.readthedocs.io/it/latest/
ENG: http://admo.readthedocs.io/en/latest/

Indici di tabelle e figure con ordine casuale

Vorrei che le figure e le tabelle nei rispettivi indici fossero ordinate per capitolo.numero. Al momento l'ordine sembra casuale.

Vedi per esempio: https://docs-italia-staging.teamdigitale.it/italia/docs-italia/docs-italia-guide/it/bozza/index/che-cos-e-docs-italia.html

Link cos'è nello header

Nei documenti, così come nella home page, ci dovrebbe essere il link a Cos'è https://docs.developers.italia.it/che-cos-e-docs-italia/

Menu sempre espansi

È voluto che gli accordion del menu siano sempre espansi, anche quando non selezionati? Ad esempio:

Mi aspetterei che solo il 5 fosse espanso, come si comportava del resto il vecchio tema. Ma forse è una cosa voluta?

Ridurre la quantità di parti mobili

Il nuovo tema è davvero molto gradevole, ma sia header che footer funzionano a scomparsa... ed anche la TOC non ha una posizione stabile (a seconda che uno faccia scroll dentro il frame della TOC o sulla parte del testo... in più la posizione dei pulsanti pdf/htmlzip/epub all'improvviso non è più in basso e scorre su (e ciò accade a seconda della lunghezza del testo del paragrafo visualizzato).

Insomma si genera un effetto mal-di-mare in cui tutto si muove. Cercherei di dare una posizione stabile a qualcosa, almeno alla TOC ed ai pulsanti pdf/htmlzip/epub, mettendo header e footer solo nella parte destra che contiene il testo.

Loghi a fondo pagina

Il logo di AgID in calce sembra più grande e leggermente più in basso rispetto a quello del Team Digitale. Dovrebbero forse avere la stessa grandezza ed essere allineati?

Eliminazione pubblicità

D'accordo con gli autori di RTD, dobbiamo inserire il seguente stile per disattivare definitivamente le pubblicità dai nostri repo:

    div.rst-pro {
        display: none !important;
    }

Introdurre meccanismo di prevenzione caching CSS

Abbiamo ricevuto segnalazione di layout visualizzati male, molto probabilmente a causa di cache persistente sui file CSS.

Introdurre un meccanismo che preveda l'utilizzo di nomi di file diversi, querystring o simile per gli asset che possano essere affetti da tale problema (JS e CSS in primis).

Box Devi, Dovresti e Potresti

In alcuni documenti sono presenti i box Devi, Dovresti e Potresti, creati nel vecchio tema con delle admonition.

Nel nuovo tema la vecchia sintassi sembra non funzionare (vedi qui: https://docs-italia-staging.teamdigitale.it/italia/designers-italia/lg-comunicazione-docs/it/stabile/doc/intro_linee-guida.html)

È prevista questa funzionalità nel nuovo tema? In caso negativo, come modifichiamo i vecchi documenti? Usiamo delle admonition normali?

Uso del tema per raccolta dati analytics

Si potrebbe utilizzare il tema per integrare, in tutti i documenti che lo usano, il codice di tracciamento per la raccolta di dati analytics.
Issue segnalata da @sbronzolo.