[bglug] Software Web per Documentazione Aziendale

[omar lazzari]

Nello stesso modo funziona Hugo, che come Sphinx e tanti altri, è uno
static site generator
https://themes.gohugo.io/hugo-theme-techdoc/
Si crea una struttura di sottocartelle per suddividere argomenti, capitoli,
sottocapitoli etc... il tutto scritto in markdown preferibilmente.
Hugo crea il sito statico corrispondente al template scelto.

MediaWiki però è molto comodo considerate tutte le estensioni esistenti che
la comunità col tempo ha sviluppato.
Trovo comodissimo lo strumento di ricerca, indispensabile se non si è molto
ordinati nella creazione delle voci.


Omar







On 2020-01-21 at 18:39:22 +0100, Marco Cavallini wrote:
> > [...]
> > Il tutto deve essere editabile da interfaccia web e consultabile da
> > browser, meglio se OpenSource.
> > [...]
> Il kernel linux usa Sphinx
> http://www.sphinx-doc.org/en/master/
>
> Una comoda alternativa è ReadTheDocs
> https://readthedocs.org/

che poi sono circa la stessa cosa, o sbaglio? readthedocs non è
semplicemente una piattaforma per pubblicare documenti realizzati con
sphinx?

È una soluzione che uso anche io, ma credo che manchi l'interfaccia web
per la modifica, a meno che esistano tool che non conosco (e nel caso
quali sono?)

Come alternativa, anche questa che uso, file reStructuredText (lo stesso
formato di sphinx) dentro ad un repository su un gitlab selfhostato.

Ha lo svantaggio di richiedere un gitlab, che è un discreto malloppone
(da noi è già presente per altri motivi), ma a quel punto è comodo da
usare sia per chi preferisce scrivere nell'interfaccia web che per chi
preferisce usare il suo editor, offre la visualizzazione via web
(rendering automatico dei file reST), ma anche un modo comodo per avere
una copia locale di tutto quanto.

Ci sono un po' di ticket aperti per chiedere a gitlab di supportare
alcuni dei costrutti di sphinx, in modo da permettere l'unione delle due
cose (file in gitlab, editabili online, con preview veloce sul
repository e pubblicazione nei vari formati (html, pdf, epub) tramite
sphinx), che sarebbe una soluzione ideale, ma ancora non funziona
completamente.

https://gitlab.com/gitlab-org/gitlab/issues/36219

https://gitlab.com/gitlab-org/gitlab/issues/26687
-------------- parte successiva --------------
Un allegato HTML è stato rimosso...
URL: <http://lists.linux.it/pipermail/bglug/attachments/20200122/e7427abd/attachment.htm>