En 2023, había estado codificando para proyectos de datos durante 2 años y estaba buscando crear mi primer portafolio para presentar mis proyectos de ciencia de datos. Descubrí la Artículo de Matt Chapman sobre el TDS y el Portafolio de Matt ChapmanEste artículo correspondía perfectamente a mis conocimientos técnicos en ese momento (Python, Git). ¡Gracias al artículo de Matt Chapman, comencé mi primer portafolio! Así que decidí explorar esta solución y descubrir cómo hacerlo. Descubrí La referencia que utilizó Matt Chapman y el repositorio correspondienteUtilicé esta referencia para crear mi portafolio.
En 2024, descubrí que mi antiguo portafolio era anticuado en comparación con los portafolios existentes y no muy atractivo para los entusiastas de los datos o los reclutadores. Al explorar los proyectos que ya se han llevado a cabo en la comunidad, encontré varios proyectos con una documentación excelente. Aquí hay 2 enlaces que me inspiraron: Documentación de varias páginas basada en GitHub Pagesy Portafolio de JavaScript basado en páginas de GitHub y Artículo correspondiente de Medium.
Para esta nueva edición de mi portafolio, mis criterios fueron: una solución gratuita, con una configuración mínima. Al revisar la documentación y los portafolios existentes, tenía varias opciones:
- Opción 1: Mantener la misma apariencia visual y arquitectura de mi portafolio anterior
- Opción 2: Bifurcar el portafolio de JavaScript mencionado anteriormente
- Opción 3: Utilizar el documentos mk Paquete de Python
Como no codifico en JavaScript, me habría limitado rápidamente en cuanto a la personalización, así que preferí pasar. El uso de una sola página de GitHub como en mi portafolio anterior no fue una mejora suficiente en mi portafolio. Durante mi investigación, descubrí dos subpaquetes de mkdocs que me llamaron especialmente la atención por las imágenes que ofrecían: material de mkdocs y Solo los documentosFinalmente elegí mkdocs por tres razones:
- El paquete (mkdocs) es fácil de usar y conozco Python y Git, que son las 2 tecnologías necesarias.
- El contenido del sitio web está en Markdown y el paquete genera automáticamente el sitio con un mínimo de acción de mi parte en el repositorio de GitHub.
- El sitio web generado es hermoso y funcional.
Mkdocs-material permite el uso de etiquetas de Google, ¡perfecto para rastrear el tráfico en mi portafolio!
En el momento de este proyecto, ya había configurado mis páginas de GitHub, creado mi repositorio y creado el entorno virtual para mi portafolio anterior. Para que todos puedan seguir y reproducir este artículo, he decidido empezar desde cero. Aquellos de ustedes que ya tienen un portafolio de páginas de GitHub, ya están familiarizados con Git y Python y podrán conservar las ramas sin preocupaciones.
En este artículo, compartiré algunos enlaces URL. Mi objetivo es brindarte una buena comprensión de cada aspecto del código y, si es necesario, brindarte recursos para profundizar más en un tema o resolver un error que no he descrito en mi artículo.
Software necesario
Para este trabajo, necesitarás tener al menos Python y Git instalados y configurados en tu computadora, y una cuenta de GitHub. Personalmente, trabajo en VSCode y Miniconda integrada en PowerShell para poder tener mis scripts y terminal en la misma pantalla. Para configurar Git, te remito a la Tu identidad parte de la página en el Sitio Git.
Configurar el entorno local
yo trabajo con MinicondaSi trabajas con la misma herramienta, reconocerás el ‘(base)>’ elementos. En caso contrario, este elemento representa el entorno virtual de Python actual (base es el entorno virtual predeterminado de Miniconda). El elemento `carpeta de trabajo` es la carpeta actual de la terminal.
1. El primer paso es crear el entorno virtual para el proyecto de portafolio:
(base)> conda create -n "portfolio_env" # Create the new virtual env named portfolio_env
(base)> conda activate portfolio_env # Activate the new virtual env, (base) become (portfolio_env)
2. En este nuevo entorno, necesitamos instalar los paquetes de Python:
(portfolio_env)> pip install mkdocs mkdocs-material
3. Para garantizar la reproducibilidad de su entorno, exportamos los requisitos:
(portfolio_env)> conda env export > "environnement.yml" # Export the environment.yml file, to ensure conda env repoductibility (including the python version, the conda env configuration, … )
(portfolio_env)> conda list > "requirements.txt" # Export packages installed only
Crear la carpeta de trabajo
Mi cartera anterior no usaba mkdocs, así que creo la estructura mkdocs:
(portfolio_env)> mkdocs new "<your GitHub username>.github.io"
Reemplazar
<your GitHub username>.github.io
|- mkdocs.yml
|- environment.yml
|- requirements.txt
|- docs/
|- index.md
Para comprender el paquete mkdocs, encontrará la documentación aquí.
PAGreparar Git
Si ya tienes una página de GitHub, puedes clonar tu
- Crea un archivo llamado readme.md. Este archivo es el archivo README clásico para cualquier repositorio Git
- Abra una terminal Git y cree el repositorio local
working_folder> git init # Initiate the local repo
working_folder> git add . # Save the readme file
working_folder> git commit -m "Initiate repo" # Commit changes
3. En su cuenta de GitHub, cree un nuevo repositorio llamado
4. Conecte el repositorio local con el repositorio remoto. En la terminal de Git:
working_folder> git remote add github https://github.com/<your GitHub username>.github.io
Si no está familiarizado con GitHub Pages, el Páginas del sitio web de GitHub Te los presentaré y te explicaré por qué los uso.
La carpeta de trabajo tendrá la siguiente arquitectura:
<your GitHub username>.github.io
|- .git
|- readme.md
|- mkdocs.yml
|- environment.yml
|- requirements.txt
|- docs
|- index.md
Alimentar el sitio web
Mkdocs te permite visualizar el sitio web e incluir modificaciones de forma dinámica, para que puedas ver cómo evoluciona tu sitio con el tiempo. El código para generar el sitio de forma dinámica:
mkdocs serve
Este comando devuelve una URL local (por ejemplo 127.0.0.1:8000) para pegar en el navegador.
readme.md y index.md
El archivo readme corresponde a la página de inicio del repositorio remoto. Cuando creaste la carpeta de trabajo con el paquete mkdocs, se creó una docs/index.md archivo que corresponde a la página de inicio del sitio.
El menú
El primer paso es configurar el menú del sitio web (el panel izquierdo, para navegar entre páginas). carpeta_de_trabajo/mkdocs.yml archivo, este es el Navegación parte:
# Page tree: refer to mkdocs documentation
nav:
- Home: index.md
- Current project:
- "Health open data catalog": catalogue-open-data-sante/index.md
- Previous data science projects:
- "Predict Health Outcomes of Horses": horse_health_prediction_project/readme.md
…
- Previous skills based projects:
- "Predict US stocks closing movements": US_stocks_prediction_project/readme.md
…
El Hogar El elemento es importante: esta es la página de inicio del sitio web. Puede elegir duplicar el Léame.md archivo dentro del índice.md archivo para tener la misma página de inicio en el repositorio de GitHub y el sitio web, o escribir uno nuevo índice.md archivo para tener una página de inicio específica para su portafolio.
Vamos a desglosar el siguiente bloque:
- Previous data science projects:
- "Predict Health Outcomes of Horses": horse_health_prediction_project/readme.md
…
Proyecto de ciencia de datos anterior: representará el nombre de un grupo de páginas en la barra de navegación. “Predecir los resultados de salud de los caballos” será el nombre que se mostrará en el menú del archivo indicado, en este caso: proyecto_de_predicción_de_la_salud_de_los_caballos/readme.md . Mkdocs encuentra automáticamente las páginas que se mostrarán en la carpeta docs, por lo que no es necesario especificarlo en la ruta. Sin embargo, como el proyecto de predicción de la salud de los caballos se presenta en una carpeta homónima, debe especificar en qué carpeta se encuentra el archivo que desea mostrar.
En el documentos/ carpeta, agrego mi proyecto anterior:
working_folder
|- docs
|- horse_health_prediction_project
|- readme.md
|- notebook.ipynb
|- notebook.html
|- US_stocks_prediction_project
|- reamd.me
|- notebook.ipynb
|- notebook.html
Luego agrego la presentación de cada proyecto en la barra de navegación con la siguiente sintaxis: `“
La sangría aquí es muy importante: define las carpetas de la barra de navegación. No es necesario que todos los archivos de la carpeta docs aparezcan en la barra de navegación. Sin embargo, si no aparecen en la lista, el visitante no podrá acceder a ellos directamente.
Configuración del sitio web
Luego configuro aspectos invisibles pero muy importantes de mi web:
- Información básica del sitio web solicitada por mkdocs-material:
# Project information
site_name: Pierre-Etienne's data science portfolio
site_url: https://petoulemmonde.github.io/
site_author: Pierre-Etienne Toulemonde
site_description: >-
I'am Pierre-Etienne Toulemonde, PharmD and Data scientist,
and you are here on my data science portfolio
El nombre del sitio correspondiente al nombre en la pestaña del navegador.
- Algunas informaciones del repositorio para permitir que mkdocs-material muestre información en la esquina superior derecha del repositorio que aloja el sitio:
# Repository: necessary to display the repo on the top right corner
repo_name: petoulemonde/petoulemonde.github.io
repo_url: https://github.com/petoulemonde/petoulemonde.github.io
- Defino aquí el diseño a utilizar:
# Configuration:
theme:
name: material
Es un paso muy importante porque esta línea le dice a mkdocs: ‘Use el paquete mkdocs-material para crear el sitio web’. Si omite este paso, las páginas de GitHub no tendrán las funciones y el aspecto visual de mkdocs-material.
Añado información adicional para hacer el seguimiento del tráfico en mi sitio web:
# Additional configuration
extra:
analytics:
provider: google
property: <your google analystics code>
El propiedad es un código de Google Analytics, para rastrear el tráfico en mi cartera. El código se genera con Google Analytics y está vinculado a mi cuenta de Google (puede encontrar un tutorial para crear su código) aquí).
Por supuesto, no escribí todo el archivo de una sola vez. Empecé a agregar archivos de un proyecto e información en la arquitectura del archivo y en la barra de navegación, luego la configuración, luego otro proyecto, luego la configuración, …
El final mkdocs.yml archivo
Mi final mkdocs.yml El archivo es:
# Project information
site_name: Pierre-Etienne's data science portfolio
site_url: https://petoulemonde.github.io/
site_author: Pierre-Etienne Toulemonde
site_description: >-
I'am Pierre-Etienne Toulemonde, PharmD and Data scientist,
and you are here on my data science portfolio# Repository
repo_name: petoulemonde/petoulemonde.github.io
repo_url: https://github.com/petoulemonde/petoulemonde.github.io
# Configuration
theme:
name: material
# Additional configuration
extra:
analytics:
provider: google
property: <google analystics code>
# Page tree
nav:
- Home: index.md
- Current project:
- "Health open data catalog": catalogue-open-data-sante/index.md
- Previous data science projects:
- "Predict Health Outcomes of Horses": horse_health_prediction_project/readme.md
…
- Previous skills based projects:
- "Predict US stocks closing movements": US_stocks_prediction_project/readme.md
…
La estructura final del archivo
En este paso, mi estructura de archivos es:
petoulemonde.github.io
|- .git
|- readme.md
|- mkdocs.yml
|- requirements.txt
|- environnement.yml
|- docs/
|- index.md
|- US_stocks_prediction_project/
|- README.md
|- notebook.ipynb
|- notebook.html
|- horse_health_prediction_project/
|- README.md
|- notebook.ipynb
|- notebook.html
|- … others projects …
Implementar el trabajo
Mkdocs permite generar el código para el sitio web en 1 línea de comando:
mkdocs gh-deploy
¡Mkdocs traduce todos los archivos mkdocs a un sitio web HTML, como un mago! Los enlaces Markdown se transforman en enlaces HTML y se genera el mapa del sitio.
Luego, confirme todos los cambios en el repositorio local y envíelos al repositorio remoto.
working_folder> git add .
working_folder> git commit -m "Create website"
working_folder> git push github master
Para configurar una página de GitHub, los pasos son:
- Siga los pasos anteriores para impulsar una cartera mínima
- En GitHuben la página de inicio del repositorio remoto, haga clic en ‘Ajustes‘ (menu principal)
- En el menú de la izquierda, haga clic en ‘Páginas‘
- Configurar la página:
– Fuente: implementar desde una rama
– Rama: Implementación de gh y /raíz
– luego guardar
En el menú superior, haga clic en ‘Comportamiento‘. Deberías ver un ‘flujo de trabajo en ejecución’. Déjalo ahí y, tan pronto como esté verde, estará bien, ¡tu sitio estará en línea! ¡Bien hecho, lo lograste!
Puedes ver tu sitio web en https://
Cuanto más miro mi portafolio para revisarlo y presentarlo, más errores veo. Para corregirlos, nada podría ser más sencillo:
- Realizar cambios en su computadora (para echar un vistazo rápido a la modificación realizada y realizar otras si es necesario, recordatorio rápido: `mkdocs sirve`)
- Regenerar el sitio usando `mkdocs gh-implementación`
- Confirmar todos los cambios
- Empujar hacia el repositorio remoto.
Y ocurre la magia: GitHub realiza automáticamente la modificación (mira el ‘Comportamiento‘ pestaña para ver dónde se encuentra GitHub).
Encontrarás mi portfolio edición 2024 aquí y el repositorio de GitHub aquíEn el futuro, me gustaría integrar JavaScript para hacer el portafolio más dinámico.
¿Por qué no compré un sitio web para mi portafolio? Me gustaría concentrarme en crear contenido para mi portafolio y nuevos proyectos, y mantener el aspecto administrativo de estas tareas al mínimo. Además, tanto en el caso de un sitio web como en el de GitHub Pages, las personas se enterarán del proyecto haciendo clic en un enlace que los redirija a mi sitio, por lo que, ya sea que compre un sitio web o no, el resultado será el mismo.
Muchas gracias por su atención, este fue mi primer artículo en Medium. No duden en responder al artículo, me encantaría saber qué piensan. ¡Nos vemos pronto!