Publicar

GitHub es un sitio web que hostea sobre todo proyectos de software libre de forma gratuita. Una alternativa similar y libre es GitLab, que además de tener un servidor gratuito GitLab.com permite hostear tu servidor privado.

La función principal de ambos es hostear repositorios Git, pero agregan más funciones como Wikis, Issues, y además permiten hostear una pagina web estática para el proyecto que en este caso va a ser la documentación generada con Sphinx.

La funcionalidad del hosteo de sitios web se llama GitHub Pages o GitLab Pages. Se necesita saber algo sobre Git para poder usarlos.

GitHub

Para este caso creo que lo mejor es poner los archivos html generados en una branch llamada github-pages usando git subtree.

Por primera vez

Primero se puede crear el repositorio en GitHub, luego creamos el repositorio Git en nuestra PC y subimos el código.

Al crear el repositorio en GitHub se muestra una dirección que se debe usar para subir los cambios. Si se usa la dirección que empieza con https:// hay que poner la contraseña de GitHub cada vez que se suban modificaciones, si se usa la dirección que empieza con git@ previamente hay que agregar la clave pública de SSH de la PC a la cuenta de GitHub. Yo voy mostrar un ejemplo de cuando se usa SSH, por eso más abajo usé la URL que empieza con git@

sudo apt install git # instalar git
cd proyecto # ir a la raíz del proyecto

git init # inicializar el repositorio git
git remote add origin git@github.com:usuario/proyecto.git # indicar URL de GitHub

# antes de continuar es necesario ya tener la documentación generada:
cd docs
make html
cd ../

git add -A # agregar todos los cambios al commit
git commit -m "commit inicial" # crear commit
git push -u origin master # subir cambios

# ahora subiremos al directorio con los documentos html como una branch llamada gh-pages
git subtree push --prefix docs/build/html origin gh-pages

En este momento ya se puede ingresar a https://usuario.github.io/proyecto/ y se debería ver la documentación de nuestro proyecto.

Actualizar documentación

Cuando se quiera actualizar la documentación, se debe generar nuevamente con make html y repetir los últimos comandos.

cd docs
make html
cd ../

git add -A # agregar todos los cambios al commit
git commit -m "cambios realizados" # crear commit
git push origin master # subir cambios

# actualizar la branch gh-pages
git subtree push --prefix docs/build/html origin gh-pages

GitLab

Creo que los pasos dependen de si se va a publicar el sitio en GitLab.com o en un servidor de GitLab propio.

Por ahora dejo un link a las instrucciones