TecNoticias, tu portal de información

Tutorial paso a paso sobre cómo usar Sphinx con canalizaciones Vertex AI.

Por @sigmund, unsplash.comEl propósito de este artículo es compartir el procedimiento para usar Sphinx para generar automáticamente la documentación de su proyecto de aprendizaje automático. Voy a usar funciones avanzadas de Sphinx, como la adición de logotipos, notas, imágenesy documentos rebajados. Además, voy a mostrar el paquete de python que necesita para que Sphinx pueda extraer las cadenas de documentación presentadas en sus canalizaciones de Vertex. ¡Comencemos! Como sabrá, tener documentación actualizada para sus proyectos de aprendizaje automático es vital tanto para la fase de producción como de prueba de concepto. ¿Por qué es vital? Porque ayuda a aclarar y simplificar sus módulos, colaborar con su equipo, integrar rápidamente a un nuevo miembro del equipo, hacer evoluciones más rápidas y compartir con los dueños de negocios. Personalmente, he experimentado muchos casos en los que debido al tiempo de comercialización restricciones, la documentación se ignoró, pero esto resultó ser fatal una vez que el proyecto se lanzó a producción. Por lo tanto, le aconsejo que evite cualquier procedimiento manual para generar su documentación, ya que dichos procedimientos siempre terminan desincronizándose y consumen mucho tiempo. Por lo tanto, antes de publicar su proyecto, tómese un tiempo para verificar la legibilidad de su proyecto. En mi caso, tiendo a usar los siguientes archivos:LÉAME— un archivo fácil de leer que proporciona una introducción e información general sobre el proyecto, como el propósito, la información técnica, los componentes del softwareLICENCIA — un archivo que menciona el procedimiento paso a paso de la licencia a seguir para los contribuyentesUSO — un archivo para explicar cómo usar el proyectoREGISTRO DE CAMBIOS — un archivo que rastrea los cambios y las versiones publicadas del proyecto Tenga en cuenta que el archivo más importante es el README. La información de contribución y uso se puede agregar directamente al archivo Léame. El archivo de registro de cambios se puede agregar más adelante antes de lanzar el proyecto en producción. Para editar los archivos, puede usar Markdown, texto simple o reStructuredText.Vea a continuación la descripción general del proceso que vamos a describir.Descripción general del proceso (Imagen del autor) ¿Qué es Sphinx? Sphinx es una herramienta de autogeneración de código abierto potente y fácil de usar, muy utilizada por la comunidad de Python. Es capaz de generar una excelente documentación estructurada. Existen algunas alternativas como MkDocs, Doxygen, pdoc y otras, pero Sphinx sigue siendo un competidor fuerte completo y fácil de usar. Las características principales: soporte para varios formatos de salida: HTML, PDF, texto sin formato, EPUB, TeX , etc.generación automática de la documentacióngeneración automática de enlacessoporte multi-idiomavarias extensiones disponibles

I. Configurar el entornoII. Instalar un entorno virtual III. Instale Esfinge IV. Configurar SphinxV. Construir la documentación

I. Configurar el entorno

Python 3Máquina virtual local o Vertex AI Workbench (cuaderno Jupyter que se ejecuta en un entorno virtual con Python 3) Proyecto de Python que contiene Vertex AI codeVirtualenvkfx — extensión para el analizador sdkMyST de la canalización de kubeflow — sabor del proyecto MarkdownVertex que contiene canalizaciones de sdk Usemos un punto a punto ejemplo de código abierto de una canalización Vertex AI bajo la licencia Apache-2.0. El proyecto es un buen ejemplo ya que el proyecto usa canalizaciones Vertex y no usa un generador de documentación. Primero, clone el código fuente y vaya a la vertex-pipelines-end-to-end-samples directorio: clon de git https://github.com/GoogleCloudPlatform/vertex-pipelines-end-to-end-samples.git
cd vertex-pipelines-end-to-end-samplesII. Crea un entorno virtual y actívalo

tercero Instalar esfinge

Cree un archivo requirements-sphinx.txt y agregue :myst-parser==0.15
solicitudes == 2.28.1
esfinge==4.5.0
esfinge-clic==4.3.0
esfinge-yo==0.3
esfinge-rtd-tema==1.0.0
primero2pdf==0.99
kfxInstall inmediatamente Sphinx y sus extensiones enumeradas en los requisitos-sphinx.txt: pip install -r requisitos-sphinx.txt Cree un directorio docs (si no existe) para almacenar el diseño de Sphinx: mkdir docs
cd docs Generar la estructura de directorio inicial con sphinx-inicio rápido dominio:sphinx-inicio rápidoElija fuentes separadas y directorios de compilación, el nombre del proyecto, el nombre del autor, la versión del proyecto y el idioma del proyecto. Puede encontrar a continuación mi configuración:Debe obtener la siguiente estructura de árbol:Como puede ver, elegimos separar los directorios de compilación y fuente. Vamos a dar algunas explicaciones sobre su contenido. El construir/ directorio está destinado a mantener la documentación generada. Está vacío por ahora ya que aún no tenemos ninguna documentación generada. hacer.bat (Windows) y Makefile (Unix) Los archivos son scripts que simplifican la generación de documentación. fuente/conf.py es el archivo de configuración del proyecto Sphinx. Contiene las claves de configuración predeterminadas y la configuración que especificó para sphinx-quickstart. fuente/index.rst es el documento raíz del proyecto que contiene la directiva del árbol de tabla de contenido (toctree) donde debe enumerar todos los módulos que desea incluir en su documento. _estático El directorio contiene hojas de estilo personalizadas y otros estático archivos. Los _plantillas El directorio almacena las plantillas de Sphinx.

IV. Configurar Esfinge

Identifique los módulos de python: /pipelinesEl directorio /tuberías contiene el código python que queremos incluir en la documentación de Sphinx. Nota que Sphinx ve los submódulos presentes en el paquete de canalizaciones solo si agrega un archivo __init__.py en /tuberías directorio.Generar las fuentes de SphinxUtilice sphinx-apidoc para crear la documentación de su API (asegúrese de estar en la raíz del proyecto). Las fuentes de Sphinx creadas se almacenan en docs/source/pipelines.
sphinx-apidoc -f -o docs/source/pipelines pipelines/ Puede verificar que los siguientes archivos se crearon en docs/source/pipelines:Copie los archivos de rebajas en docs/sourceCopie los archivos README.md, CONTRIBUTING.md y USAGE.md automáticamente en el directorio fuente de Sphinx (docs/source/). Agregue en los documentos/Makefile las siguientes líneas para automatizar la sincronización de los archivos de rebajas: COPY_README = ../README.md
COPIA_CONTRIBUCIÓN = ../CONTRIBUCIÓN.md
COPY_USAGE = ../USAGE.md#sincronyze archivos MD
$(shell cp -f $(COPY_README) $(SOURCEDIR))
$(shell cp -f $(COPIA_CONTRIBUCIÓN) $(SOURCEDIR))
$(shell cp -f $(COPIA_USO) $(SOURCEDIR))Edite el index.rstUsar la Nota directiva para la información que desea resaltar… nota:: Sphinx con Vertex AI.Use imagen directiva para añadir una imagen. El tamaño de imagen recomendado tiene un ancho entre 400 y 800 píxeles… imagen:: ../images/xgboost_architecture.png
:Alinear al centro
:ancho: 800px
:alt: texto alternativoBajo el árbol de toc directiva enumera todos los módulos que desea que se incluyan en la documentación final (README, módulos)… toctree::
:máx. profundidad: 2
:caption: Contenido: LÉAME
tuberías/módulos
CONTRIBUYENDO
USO Encuentre mi index.rst a continuación:Edite conf.py: el archivo de configuración principal de SphinxDefina la ruta: # Defina la ruta
sys.path.insert(0, os.path.abspath(“../..”))Agregue sus extensiones:extensiones = [
“sphinx.ext.duration”,
“sphinx.ext.doctest”,
“sphinx.ext.viewcode”,
“sphinx.ext.autosummary”,
“sphinx.ext.intersphinx”,
“sphinx_rtd_theme”,
“sphinx_click”,
“myst_parser”,
“sphinx.ext.todo”,
“sphinx.ext.coverage”,
“myst_parser”,
]Enumere la lista de archivos que se analizarán: source_suffix = {
“.rst”: “texto reestructurado”,
“.md”: “rebaja”,
}Especifique el tema HTML:html_theme = “sphinx_rtd_theme”Para agregar un logo asegúrese de que la imagen esté presente en fuente/_estática. He usado el logotipo de Vertex AI. Luego puede definir la ruta del logotipo: html_logo = “_static/vertex.png” Enumere todos los enlaces externos presentes en los archivos de descuento: intersphinx_mapping = { “python”: (“https://python.readthedocs.org/en/latest /”, Ninguno)}Ver mi archivo de configuración conf.py:

V. Construir la documentación

Para generar documentación HTML con Sphinx, vaya a /docs y use el comando:make htmlUse Firefox para abrir la página HTML:firefox docs/build/html/index.htmlSi logró seguir todos los pasos, debería poder ver un página HTML más atractiva.

La extensión KFX permitirá que Sphinx lea los componentes, nombres de funciones, parámetros y cadenas de documentación de Kubeflow.

Automatice la construcción de la documentación utilizando el Makefile (presente en la raíz del proyecto). Edite el Makefile y agregue las siguientes líneas: create-sphinx-sources:
cd documentos; hacer limpia; discos compactos ..; rm -r docs/source/pipelines; sphinx-apidoc -f -o docs/source/pipelines pipelines/generar-doc:
@ $(MAKE) create-sphinx-sources && \
cd documentos; make htmlLuego llama al make generate-doc:make generate-docLlegamos al final de nuestro viaje con Sphinx. ¡Espero que haya encontrado útil el contenido! Hemos visto cómo usar Sphinx, una poderosa herramienta para generar documentación para su proyecto de aprendizaje automático. Hemos personalizado la documentación con logotipos, imágenes y contenido de rebajas. Por supuesto, Sphinx viene con muchas otras extensiones que puede usar para hacer que su documentación sea aún más atractiva.