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:
Descargue el instalador de Git desde el sitio web oficial: gitforwindows.org .
Ejecute el instalador y siga las instrucciones. Puede aceptar las configuraciones por defecto o personalizarlas según sus preferencias.
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.
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.
Abra una terminal en su sistema Linux.
Actualice la lista de paquetes con el comando:
sudo apt update
Instale Git con el siguiente comando:
sudo apt install git
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.
Configure Git para su identificación como autor de futuras contribuciones.
git config --global user.name "Su Nombre"
git config --global user.email "su@email.com"
Importante
Utilice el mismo correo electrónico que utilizó para registrarse en GitHub .
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.
Diríjase al repositorio de la documentación en github.com/linkaform/documentation .
Elija la rama
develop
.
Presione
Fork
para crear una copia personalizada del repositorio.
Clone el repositorio.
git clone git@github.com:Linkaform/documentation.git
Abra una terminal y ubíquese en el directorio del repositorio.
cd documentation
Cree una rama.
git branch
git branch nombre-de-la-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
Realice sus modificaciones.
Para ver que archivos han sufrido cambios, en una nueva terminal ejecute:
git status
Agregue los cambios a su rama.
git add .
git add nombre_del_archivo.rst
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.
Envíe sus cambios a GitHub.
git push origin [Nombre de la Rama]
Diríjase de nuevo a GitHub, específicamente a su rama y presione el botón
Pull request
.Describa todos los cambios que ha realizado.
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.
Descargue
Python
en el sitio web oficial python.org (seleccione la versión estable y adecuada para su sistema).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
ypip
desde la línea de comandos.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:
Actualice la lista de paquetes:
sudo apt update
Instale
Python 3
ypip
.
sudo apt install python3 python3-pip
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 .
Descargue Docker Desktop en el sitio web oficial de Docker.
Ejecuta el instalador y siga las instrucciones.
Inicie Docker Desktop.
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.
En su terminal, navegue a la carpeta que corresponde a la documentación.
cd documentation
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.
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.
Como último paso, ejecute el siguiente comando según su SO.
bash local_build
local_build
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.