Documentazione delle funzioni ("Documentatore")

A partire dalla 4.6.10 è stata rilasciata una prima versione della nuova funzionalità del webadmin che permette di comporre la documentazione delle funzioni.

Per abilitare la funzionalità è necessario:

1. una versione del webadmin pari o superiore alla versione 4.6.10
2. aggiornare i metadati con lo script per la creazione della tabella gwm_projects_doc (vedi sotto)
3. rimuovere i nomi duplicati dei menu (valore della proprietà “name” ) in tutti i project.xml.

--postgres
   CREATE TABLE {{metadata_schema_name}}.gwm_projects_doc (
    gwid integer NOT NULL,
    project_name character varying(50) COLLATE pg_catalog."default" NOT NULL,
    name character varying(100) COLLATE pg_catalog."default" NOT NULL,
    description character varying COLLATE pg_catalog."default",
    hidden integer,
    update_date timestamp without time zone,
    version character varying(50) COLLATE pg_catalog."default",
    CONSTRAINT gwm_projects_doc_pkey PRIMARY KEY (gwid),
    CONSTRAINT uk_project_name_name UNIQUE (project_name, name)
    )

--oracle
CREATE TABLE GWM_PROJECTS_DOC
(
  GWID NUMBER(*,0) NOT NULL,
  PROJECT_NAME VARCHAR2(50) NOT NULL,
  NAME VARCHAR2(100) NOT NULL,
  DESCRIPTION VARCHAR2(4000),
  HIDDEN NUMBER(*,0),
  UPDATE_DATE DATE,
  VERSION VARCHAR2(50),
  CONSTRAINT GWM_PROJECTS_DOC_PKEY PRIMARY KEY (GWID),
  CONSTRAINT UK_PROJECT_NAME_NAME UNIQUE (PROJECT_NAME, NAME)
);

  

Il componente per la gestione della documentazione utilizza il nome del progetto e i nomi dei menu (1° livello, accordion e secondo livello) come codici identificativi del testo della documentazione (per progetto). Questo significa che se due o più menu hanno lo stesso nome, significa che condividono la stessa identica documentazione (solo in alcuni casi limite potrebbe avere senso).

Quindi la prima cosa da fare è correggere l'xml di progetto in modo che non ci siano nomi duplicati.

A tale scopo può essere utilizzato il nuovo “albero dei menu di progetto“ descritto sotto. Nell'albero sono resi evidenti i menu duplicati (con un simbolo dallo sfondo arancione). Per ogni coppia di duplicati sarà sufficiente rinominare uno dei due per rendere valido l'xml.

Le funzioni di documentazione sono state sviluppate per la realizzazione della documentazione delle *piattaforme geoweb* e per questo motivo sono state testate e ottimizzate specificatamente per questo obbiettivo. Nel caso di “documentazione delle funzioni di prodotto” sono necessari ulteriori configurazioni

1) aggiungere in ogni configuration.properties dei webadmin dei moduli di prodotto, i due parametri

 codModule= #codice del modulo comì come specificato nella cartella gwa_module
 gwa.schema= #nome dello schema principale di prodotto, quello che contiene le gwa
    

2) aggiungere nel configuration.properties del webadmin del modulo che dovrà comparire per primo nella documentazione (cioè che nella tabella gwa_module ha num_order=1), le proprietà:

 gwa.module1.webadmin.url=
 gwa.module2.webadmin.url=
 gwa.module3.webadmin.url=
 ...

in cui specificare gli indirizzi degli altri webadmin che costituiscono i moduli di prodotto, nell'ordine in cui dovranno comparire (rispettando il num_order di gwa_module ).

Per generare l'intera documentazione di una o più soluzioni è quindi richiesto che siano compilati le documentazioni di tutte le funzioni di tutti i moduli che compongono le soluzioni (nei differenti admin).

Dall'admin del modulo principale sarà possibile visualizzare l'anteprima completa del manuale di una soluzione andando a selezionare il nodo soluzione dell'albero dei progetti dell'admin.

===== Documentazione delle “soluzioni” di prodotto ===== Inoltre, nel caso di “documentazione delle funzioni di prodotto”: 1) aggiungere in ogni configuration.properties dei webadmin dei moduli di prodotto, i due parametri codModule= #codice del modulo comì come specificato nella cartella gwa_module gwa.schema= #nome dello schema principale di prodotto, quello che contiene le gwa 2) aggiungere nel configuration.properties del webadmin del modulo che dovrà comparire per primo nella documentazione (cioè che nella tabella gwa_module ha num_order=1), le proprietà: gwa.module1.webadmin.url= gwa.module2.webadmin.url= gwa.module3.webadmin.url= … in cui specificare gli indirizzi degli altri webadmin che costituiscono i moduli di prodotto, nell'ordine in cui dovranno comparire (rispettando il num_order di gwa_module ). Per generare l'intera documentazione di una o più soluzioni è quindi richiesto che siano compilati le documentazioni di tutte le funzioni di tutti i moduli che compongono le soluzioni (nei differenti admin). Dall'admin del modulo principale sarà possibile visualizzare l'anteprima completa del manuale di una soluzione andando a selezionare il nodo soluzione dell'albero dei progetti dell'admin.

Le nuove funzionalità di edit della documentazione sono disponibili agli utenti:

• ammininistratore
• redactor

Nel caso di un utente amministratore generico del webadmin, il menu “documentazione” è presente in un tab del dettaglio di progetto.

Nel caso dell'utente “redactor”, il webadmin presenta solo le funzionalità di edit della documentazione (come quelle dell'utente amministratore) e in più presenta un differente menu ad albero principale a sinistra: l'albero delle funzioni.

L'albero delle funzioni elenca i nomi delle funzioni/progetti suddivise per soluzione rispettando modello dati delle gwa_solution disponibili per il modulo corrente.

In altre parole, per ogni soluzione, se presente, viene mostrato il nome del modulo tecnico corrente (lo schema metadati a cui punta il webamdin) e i nomi delle funzioni (1:1 con i progetti geoweb) ad esso associato.

Andando a selezionare un nodo funzione dell'albero, si aprirà a destra un menu diviso in tre parti:

• Nella parte sinistra è rappresentato l'albero dei menu di progetto di cui è composto il project.xml.
• Nella parte centrale sono disponibili gli strumenti per l'editing della documentazione del menu selezionato a sinistra.
• Nella parte destra è mostrata l'anteprima della documentazione dell'intera funzione/progetto geoweb

Nella parte sinistra è rappresentato l'albero dei menu di progetto di cui è composto il project.xml.

• il primo nodo dell'albero rappresenta l'intestazione del progetto/funzione.
• i nodi al primo livello rappresentano i menu di 1° livello
• i nodi al secondo livello rappresentano i menu di tipo accordion
• i nodi al terzo livello rappresentano rappresenta i menu 2° livello

• Se il nome del menu è rosso, indica che la documentazione del menu è vuota
• Se il nome del menu è barrato, indica che il menu è invisibile all'utente finale (se ad esempio è di primo livello o un accordion senza menu “fratelli”) e quindi in questo caso la documentazione può essere omessa.
• Un simbolo arancione se il nome del menu è duplicato

Dopo aver selezionato un nodo dell'albero dei menu, nella parte centrale , tramite il tasto edit, è possibile inserire il testo che andrà a comporre manuale relativo a quel menu.

Alcune considerazioni

• il formato di testo da utilizzare è il Markdown (MD) https://it.wikipedia.org/wiki/Markdown
• i titoli della funzione e dei menu sono aggiunti in automatico
• il testo edit (matita), apre un nuovo strumento per l'edit di un testo con formato markdown. La barra degli strumenti fornisce dei comandi utili per la formattazione del testo e la colonna di destra permette di vedere un'anteprima immediata.
• per tornare indietro e salvare bisogna selezionare la spunta blu in alto a sinistra

• per l'inserimento di immagini vedi sotto

Importante: al momento del rilascio/aggiornamento della documentazione, le immagini devono essere copiate sul modulo principale di piattaforma.

Per aggiungere il riferimento ad immagini

1. Aggiungere le immagini nei contenuti statici nel percorso WEB\documentation\media\ )
2. Utilizzare la notazione standard markdown :

 ![[alt text]](<folderPath>)

Dove alt text è la descrizione dell'immagine.

La notazione per <folderPath> è la seguente:

  media/{{codice_modulo}}-immagine2.jpg
  

L'indicazione su “codice_modulo” è solo una convenzione in modo che le immagini di tutti i moduli di un'unica piattaforma, una volta messi nella stessa cartella, siano distinguibili (ed evitare ambiguità)

Esempio:

 ![[La mia immagine]](media/spm-immagine2.jpg)

==== Formattazione Immagini img ==== Per aggiungere il riferimento ad immagini - Aggiungere le immagini nei contenuti statici nel percorso ..images/projectdoc/ ) - Utilizzare la notazione standard markdown : !alt text(<folderPath>) Dove alt text è la descrizione dell'immagine. La notazione per <folderPath> è la seguente: img/images/projectdoc/immagine2.jpg Esempio: !La mia immagine(img/images/projectdoc/immagine2.jpg) ~~==== Formattazione Immagini img ====~~ ~~Per aggiungere il riferimento ad immagini~~ - Aggiungere le immagini nei contenuti statici nel percorso ..images/projectdoc/ ) - Utilizzare la notazione standard markdown : !alt text(<folderPath>) Dove alt text è la descrizione dell'immagine. La notazione per <folderPath> è la seguente: img/images/projectdoc/immagine2.jpg Esempio: !La mia immagine(img/images/projectdoc/immagine2.jpg)~~

Una prima versione di visualizzazione delle anteprime è stata rilasciata nella 4.6.10.

Una versione più avanzata sarà rilasciata nella 4.6.11.

work in progress