En aquest xicotet article explique els primer passos que he fet per a poder generar una primera versió d'un manual en format HTML amb un generador Python molt particular.
Necessitem tenir python3 i pip3, crec que no cal explicar ací com és la instal·lació de Python. Una vegada tinguem el sistema operatiu preparat, instal·larem sphinx amb:
$ pip install sphinx sphinx-autobuild texlive-pdftex-bin.x86_64 latexmk
$ pip freeze | grep "sphinx"
sphinx-autobuild==0.6.0
sphinxcontrib-websupport==1.0.0
Ara accedirem a la ruta on volem crear la nostra documentació, i executarem sphinx-quickstart per a començar el projecte. Li haurem de dir els paràmetres bàsics del nostre projecte, com títol, llengua en la que volem tenir la documentació, etc:
$ cd /home/joan/Documents/manual/
$ sphinx-quickstart
Una vegada generat l'entorn per a documentar, veurem els següents fitxers:$ ls
build make.bat Makefile source
$
Dins del directori source veurem el fitxer index.rst que serà l'ìndex del document (anomenat master document). La nostra documentació la deixarem dins del directori source creant un directori i tots el subdirectoris que necessitem. Per exemple, jo per a crear-me el manual de proves m'he creat el directori manual així:
$ mkdir source/manual
I és ací dins on anirem documentant els nostres documents font amb extensió .rst, que és un llenguatge de marques anomenat reStructuredText, o simplement reST.
Aquest llenguatge reST és molt similar a Markdown i pots trobar tota la documentació a https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html. Un exemple de index.rst es:
Afegirem, per cert, nous arxius especificant la seua ruta relativa al fitxer index.rst dins de la directiva toctree::, just baix de :caption: Contents:.
I, per a que veges el format, un exemple de la primera versió del manual seria aquest:
GENERACIÓ DE DOCUMENTS
Finalment, quan vullguem generar la documentació, ens possicionarem en la ruta on tenim el Makefile i el generarem amb:
$ make html
I ja tindràs la teua documentació a la ruta _build/html/index.html
En el meu exemple ràpid, així es visualitzaria en una tauleta electrònica.
I així es visualitzaria en un smartphone.
Finalment, per a la teua informació, podem personalitzar el nostre manual fent ús d'algun dels temes publicats a https://sphinx-themes.org/
