Instalación

En esta sección se presentan los pasos necesarios para instalar Sphinx en su sistema, ya sea que esté trabajando en un sistema operativo Windows o Linux.

Importante

Como requisito previo, es importante tener conocimientos básicos sobre Git.

Configuración del entorno

Linkaform utiliza GitHub para administrar sus repositorios y Git para el control de versiones, lo que permite gestionar y rastrear cambios en el código o el proyecto.

Si ya dispone de una cuenta en GitHub y tiene Git instalado, puede omitir los primeros pasos y continuar con contribución . De lo contrario, siga las siguientes instrucciones para preparar su entorno.

GitHub

Ver también

Cree una cuenta en GitHub .

Git

Siga los siguientes pasos para la instalación de Git en Windows o Linux:

  1. Descargue el instalador de Git desde el sitio web oficial: gitforwindows.org .

  2. Ejecute el instalador y siga las instrucciones. Puede aceptar las configuraciones por defecto o personalizarlas según sus preferencias.

  3. Elija si desea usar Git desde la línea de comandos o con Git Bash durante la instalación.

Truco

Se recomienda usar Git Bash.

  1. Verifique que Git se instaló correctamente abriendo Git Bash o la línea de comandos de Windows y ejecute:

git --version

Siga el siguiente video si tiene dudas.

Git no viene preinstalado en la mayoría de las distribuciones de Linux por defecto, pero está ampliamente disponible.

  1. Abra una terminal en su sistema Linux.

  2. Actualice la lista de paquetes con el comando:

sudo apt update

  1. Instale Git con el siguiente comando:

sudo apt install git

  1. Verifique la instalación usando:

git --version

Después de la instalación, las configuraciones básicas de Git son las mismas en Windows y Linux.

  1. Configure Git para su identificación como autor de futuras contribuciones.

Nombre de usuario
git config --global user.name "Su Nombre"
Dirección de correo electrónico:
git config --global user.email "su@email.com"

Importante

Utilice el mismo correo electrónico que utilizó para registrarse en GitHub .

  1. Genere una clave SSH y registrela en su cuenta GitHub. Si tiene dudas puede seguir el siguiente video tutorial.

Contribución

Las instrucciones siguientes le ayudarán a preparar su entorno para realizar cambios locales en el código base y luego enviarlos a GitHub.

  1. Diríjase al repositorio de la documentación en github.com/linkaform/documentation .

  2. Elija la rama develop.

../_images/24.png

  1. Presione Fork para crear una copia personalizada del repositorio.

../_images/25.png

  1. Clone el repositorio.

../_images/22.png 
git clone git@github.com:Linkaform/documentation.git

  1. Abra una terminal y ubíquese en el directorio del repositorio.

cd documentation

  1. Cree una rama.

Verifique las ramas actuales
git branch
Cree la rama nueva
git branch nombre-de-la-rama
Cambie a la nueva rama
git checkout nombre-de-la-rama

Ver también

Con la versión más actual de Git cree y cambie a una nueva rama al mismo tiempo.

git switch -c nombre-de-la-rama

  1. Realice sus modificaciones.

  2. Para ver que archivos han sufrido cambios, en una nueva terminal ejecute:

git status

  1. Agregue los cambios a su rama.

Agregue todos los archivos al mismo tiempo
git add .
Agregue un archivo a la vez
git add nombre_del_archivo.rst

  1. Confirme sus cambios indicando que cambios se realizaron.

git commit -m "Explicación del cambio"

Truco

El mensaje debe de ser breve y conciso, pero si requiere hacer una explicación mas amplia, puede ejecutar git commit; abrirá un editor de texto donde podrá dar más detalle sobre su commit.

  1. Envíe sus cambios a GitHub.

git push origin [Nombre de la Rama]

  1. Diríjase de nuevo a GitHub, específicamente a su rama y presione el botón Pull request.

  2. Describa todos los cambios que ha realizado.

  3. Presione Create pull request.

Nota

Después de crear un Pull request, solicite a soporte técnico que revise los cambios propuestos.

Ver también

Consulte la documentación oficial de como hacer su primer pull request

Python

Si ya cuenta con la instalación de Python y pip, continúe con la configuración de Docker. Si aún no los tiene, siga los siguientes pasos para la instalación.

  1. Descargue Python en el sitio web oficial python.org (seleccione la versión estable y adecuada para su sistema).

  2. Ejecute el instalador y siga las instrucciones del instalador. Marque la opción «Add python.exe to PATH». Esto agregará Python al PATH del sistema, lo que te permitirá ejecutar Python y pip desde la línea de comandos.

  3. Siga los pasos y verifique la instalación abriendo una ventana de comandos y ejecute:

python --version
pip --version

Puede consultar el siguiente video.

En sistemas basados en Linux, Python 3 suele venir preinstalado. Sin embargo, para asegurarse de tener la última versión de y Python y pip, siga los siguientes pasos:

  1. Actualice la lista de paquetes:

sudo apt update

  1. Instale Python 3 y pip.

sudo apt install python3 python3-pip

  1. Verifique la instalación:

python3 --version
pip3 --version

Docker

Esto es una guía breve de como instalar Docker, sin embargo, para màs detalles consulte la documentación oficial de Docker Desktop en Windows .

  1. Descargue Docker Desktop en el sitio web oficial de Docker.

  2. Ejecuta el instalador y siga las instrucciones.

  3. Inicie Docker Desktop.

  4. Verifique la instalación:

docker --version

Puede consultar el siguiente video en caso de tener dudas con las configuraciones.

La instalación de Docker en Linux es más compleja y puede variar según la distribución y sus dependencias. Para una instalación exitosa, consulte la documentación oficial de Docker Desktop en Linux y siga los pasos específicos de su distribución. Cada distribución puede requerir pasos diferentes.

Para la instalación de docker en la distribución Ubuntu de Linux puede seguir el siguiente video tutorial:

Generar documentación

Al tener su entorno listo y configurado correctamente, pruebe el contenido que se encuentra en el repositorio.

Sphinx (herramienta de software utilizada para generar documentación) lleva a cabo el proceso de conversión de documentos en formato reStructuredText (rst) a HTML. Este proceso solo es posible cuando se tienen documentos escritos y estructurados en rst y después de haber configurado el proyecto de Sphinx en archivo conf.py.

Importante

Al trabajar en un contenedor de Docker, el proceso de build difiere del que se muestra en la documentación principal de Sphinx.

Para llevar a cabo el build de su documentación, siga los siguientes pasos.

  1. En su terminal, navegue a la carpeta que corresponde a la documentación.

cd documentation

  1. Ejecute el siguiente comando.

docker-compose up -d

O si tiene la versión más reciente de docker, ejecute el siguiente comando.

docker compose up -d

La instrucción anterior se utiliza para iniciar y ejecutar el contenedor de la aplicación sin bloquear la terminal y permitir que los contenedores sigan ejecutándose en segundo plano.

  1. Después de ejecutar su contenedor Docker, ejecute el siguiente comando.

docker exec -it lkf-documentation bash

La instrucción se utiliza para abrir una sesión dentro del contenedor lkf-documentation utilizando el shell Bash. Esto permite ejecutar comandos dentro del contenedor como si estuviera en una terminal dentro de ese entorno.

  1. Como último paso, ejecute el siguiente comando según su SO.

bash local_build

local_build
../_images/16.png

El comando anterior es la que se encarga de hacer build (generar el contenido). En caso de cometer algún error, podrá verlo en la terminal.

Para poder ver el resultado, diríjase a la carpeta build y abra el archivo index.html en su navegador de preferencia.

cd documentation/build/index.html

¡Felicidades! 🎉 Ha logrado configurar su entorno y ejecutar la documentación disponible. Si tiene alguna duda, puede regresar al contenido o consultar la documentación de la sección de su preferencia. También puede comenzar a crear sus primeras secciones personalizadas con la ayuda de la siguiente sección.