Documente su proyecto de aprendizaje automático de forma inteligente | de Bildea Ana | octubre de 2022

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

El 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 utilizar 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.

¡Empecemos! 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 a limitaciones de tiempo de comercialización, se ignoró la documentación, 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 siendo desincronizados y lentos.

Entonces, 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 software
• LICENCIA — un archivo que menciona el procedimiento paso a paso de la licencia a seguir para los contribuyentes
• USO — un archivo para explicar cómo usar el proyecto
• REGISTRO 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 que puede utilizar reduccióntexto sencillo, o Texto reestructurado.

Vea a continuación la descripción general del proceso que vamos a describir.

¿Qué es Esfinge?

Sphinx es una herramienta de generación automática 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 principales características:

• soporte para varios formatos de salida: HTML, PDF, texto sin formato, EPUB, TeX, etc.
• generación automática de la documentación
• generación automática de enlaces
• soporte multi-idioma
• varias extensiones disponibles

I. Configurar el entorno

II. Instalar un entorno virtual

tercero Instalar esfinge

IV. Configurar la esfinge

V. Construir la documentación

I. Configurar el entorno

• Pitón 3
• Máquina virtual local o Vertex AI Workbench (cuaderno Jupyter que se ejecuta en un entorno virtual con Python 3)
• Proyecto Python que contiene código Vertex AI
• Entorno virtual
• kfx — mixtension para kubeflow pipeline sdk
• Analizador MyST: versión de Markdown
• Proyecto Vertex que contiene canalizaciones SDK

Usemos un extremo a extremo 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 utiliza canalizaciones de Vertex y no utiliza un generador de documentación.

Primero, clone el código fuente y vaya a la vertex-pipelines-end-to-end-samples directorio:

git clone https://github.com/GoogleCloudPlatform/vertex-pipelines-end-to-end-samples.git
cd vertex-pipelines-end-to-end-samples

II. Crea un entorno virtual y actívalo

tercero Instalar esfinge

Cree un archivo requirements-sphinx.txt y agregue:

myst-parser==0.15
requests==2.28.1
sphinx==4.5.0
sphinx-click==4.3.0
sphinx-me==0.3
sphinx-rtd-theme==1.0.0
rst2pdf==0.99
kfx

Instale de inmediato Sphinx y sus extensiones enumeradas en los requisitos-sphinx.txt:

pip install -r requirements-sphinx.txt

Cree un directorio de documentos (si no existe) para almacenar el diseño de Sphinx:

mkdir docs 
cd docs 

Genere la estructura de directorio inicial con sphinx-inicio rápido dominio:

sphinx-quickstart

Elija 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, optamos por separar los construir y el fuente directorios. Vamos a dar algunas explicaciones sobre su contenido.

los 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.

los hacer.bat (Windows) y Makefile (Unix) Los archivos son scripts que simplifican la generación de documentación.

los 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.

los 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.

los _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: /pipelines

El 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 Sphinx

Utilizar el esfinge-apidoc para construir 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/source

Copie 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
COPY_CONTRIBUTING = ../CONTRIBUTING.md
COPY_USAGE = ../USAGE.md#sincronyze MD files
$(shell cp -f $(COPY_README) $(SOURCEDIR))
$(shell cp -f $(COPY_CONTRIBUTING) $(SOURCEDIR))
$(shell cp -f $(COPY_USAGE) $(SOURCEDIR))

Edite el index.rst

Usar la Nota directiva para la información que desea resaltar.

.. note::  Sphinx with Vertex AI.

Usar imagen directiva para añadir una imagen. El tamaño de imagen recomendado tiene un ancho entre 400 y 800 píxeles.

.. image:: ../images/xgboost_architecture.png
:align: center
:width: 800px
:alt: alternate text

Bajo la árbol de toc La directiva enumera todos los módulos que desea que se incluyan en la documentación final (README, módulos).

.. toctree::
:maxdepth: 2
:caption: Contents:   README
pipelines/modules
CONTRIBUTING
USAGE

Encuentre mi index.rst a continuación:

Edite conf.py: el archivo de configuración principal de Sphinx

Defina la ruta:

# Define path
sys.path.insert(0, os.path.abspath("../.."))

Añade tus extensiones:

extensions = [
"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 = 

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 la vlogotipo de la IA de ertex . Luego puede definir la ruta del logotipo:

html_logo = "_static/vertex.png"

Enumere todos los enlaces externos presentes en los archivos de rebajas:

intersphinx_mapping = 

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 html

Use Firefox para abrir la página HTML:

firefox docs/build/html/index.html

Si logró seguir todos los pasos, debería poder ver una página HTML aún 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 docs; make clean; cd ..; rm -r docs/source/pipelines; sphinx-apidoc -f -o docs/source/pipelines pipelines/generate-doc:
@ $(MAKE) create-sphinx-sources && 
cd docs; make html

Luego llame al make generate-doc:

make generate-doc

Llegamos al final de nuestro viaje con Sphinx. ¡Espero que hayas 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.