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@``

.. code:: sh

    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.

.. code:: sh

    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`__

__ GitLab Pages_

.. _GitHub: https://github.com/
.. _GitLab: https://gitlab.com/
.. _Sphinx: http://www.sphinx-doc.org/en/stable/
.. _Git: https://git-scm.com/
.. _GitHub Pages: https://pages.github.com/
.. _GitLab Pages: https://about.gitlab.com/features/pages/