docfx C# (Cómo funciona para desarrolladores)

Introducción

DocFx C# e IronPDF son dos herramientas eficaces que generan documentación y mejoran la legibilidad y accesibilidad de la documentación del proyecto, al tiempo que agilizan los flujos de trabajo de documentación. Este post explicará cómo combinar IronPDF, una biblioteca de C# para crear documentos PDF, con DocFX, un generador de documentación de API que genera documentación de referencia de API. Los desarrolladores pueden producir rápidamente una documentación excelente y compartirla en formato PDF utilizando estas herramientas.

Cómo utilizar DocFX

1. Instalar .NET SDK 6.0+

2. Abra el PowerShell.

3. Ejecute el script uno a uno e instale la biblioteca DocFX.

4. Tras la instalación, ejecute el archivo JSON.

5. Que abre el sitio de documentación en el puerto 8080.

Introducción a DocFX

Microsoft creó el generador de sitios estáticos de código abierto y la herramienta de generación de documentación DocFX. Con la ayuda de archivos Markdown y código fuente, los desarrolladores pueden producir sitios web de documentación de aspecto profesional. DocFX es adaptable y ampliamente aplicable a una gran variedad de proyectos, ya que admite multitud de formatos de marcado y lenguajes de programación.

Los desarrolladores pueden crear tutoriales, artículos conceptuales y referencias API en su documentación utilizando DocFX. Gracias a su arquitectura adaptable, los equipos pueden personalizarla y ampliarla para satisfacer sus necesidades específicas. DocFX también ofrece funciones como referencias cruzadas, plantillas editables y compatibilidad con varios formatos de salida, como HTML y Markdown. Para obtener una descripción más detallada del funcionamiento interno y los métodos de DocFX, visite las páginas del sitio Github aquí.

Primeros pasos con DocFX

Configuración de DocFX

Utilizar DocFX es bastante sencillo. Se trata de añadir el SDK de DocFX mediante el gestor de paquetes .NET de Microsoft, NuGet. En este SDK se incluyen las bibliotecas y herramientas necesarias para incorporar contenidos web a sus aplicaciones mediante DocFX.

Crear un nuevo sitio web DocFX

En esta fase crearemos un sitio web de documentación básica en su ordenador local.

• Es necesario un conocimiento básico de las operaciones de línea de comandos.

• Se requiere una versión de .NET SDK 6.0 o posterior.

  Para instalar la versión más reciente de DocFX, asegúrese de tener instalado el SDK .NET y, a continuación, abra una herramienta de línea de comandos de terminal y escriba el siguiente comando:

dotnet tool update -g docfx

Para iniciar un docset nuevo, ejecute:

docfx init

Crea un archivo JSON con todas las configuraciones. Con la ayuda de este comando, puede crear un nuevo proyecto DocFX en el directorio de trabajo actual. Para crear el docset, ejecute:

docfx docfx.json --serve

La página web puede verse ahora en vista previa en http://localhost:8080.

Guarde sus cambios, DocFX se configura utilizando el archivo de configuración JSON. ahora estamos utilizando un nuevo terminal para ejecutar este comando para reconstruir el sitio web para previsualizar sus cambios locales:

docfx docfx.json

Características de DocFX

Flexible y ampliable

DocFX es compatible con varios formatos de marcado y lenguajes de programación, como archivos JSON, YAML y Markdown. Gracias a esta flexibilidad, los equipos pueden elegir el formato que mejor se adapte a sus necesidades y gustos. Además, la arquitectura extensible de DocFX permite a los programadores añadir y modificar sus funciones mediante plugins y plantillas, satisfaciendo así una gran variedad de necesidades de documentación.

Generación de documentación de API

DocFX es una excelente herramienta que ayuda a escribir la documentación de la API a partir de los comentarios que se encuentran en el código fuente. DocFX crea automáticamente documentación de referencia de la API, incluidos espacios de nombres, clases, métodos, parámetros y tipos de retorno, analizando comentarios de código en formatos ampliamente utilizados como XML y YAML. Esta función ahorra mucho tiempo y esfuerzo a los desarrolladores, ya que agiliza el proceso de documentación de las API de código.

Compatibilidad multiplataforma

Dado que DocFX es multiplataforma, puede funcionar en sistemas Linux, macOS y Windows. Independientemente del sistema operativo que utilice el equipo de desarrollo, esta compatibilidad multiplataforma garantiza que la generación de documentación pueda incorporarse fácilmente a diversos flujos de trabajo y entornos de desarrollo.

Búsqueda y navegación integradas

DocFX incluye funciones integradas de navegación y búsqueda en la documentación generada. El acceso rápido a la información pertinente es posible gracias a la capacidad de los usuarios para buscar en la documentación temas, API o palabras clave con facilidad. Para mejorar aún más la usabilidad y la experiencia del usuario, DocFX también crea un índice de contenidos (TOC) que facilita a los usuarios la navegación por la jerarquía de la documentación.

Integración de DocFX con IronPDF

Al combinar DocFX con IronPDF, los desarrolladores pueden aprovechar las ventajas de cada herramienta y mejorar su proceso de documentación. Los desarrolladores pueden garantizar una representación coherente en todos los dispositivos, crear documentación lista para usar fuera de línea y facilitar el uso compartido y la distribución utilizando IronPDF para convertir la documentación HTML generada por DocFX a formato PDF. Para obtener más información sobre IronPDF, consulte aquí.

Instalar IronPDF

• Inicie el proyecto de Visual Studio.
• Seleccione "Herramientas" > "Gestor de paquetes NuGet" > "Consola del gestor de paquetes".
• En la consola del gestor de paquetes de Visual Studio, escriba el siguiente comando:

Install-Package IronPdf

• También puede instalar IronPDF utilizando NuGet Package Manager for Solutions.

• Puede seleccionar el paquete IronPDF en los resultados de la búsqueda y, a continuación, hacer clic en la opción "Instalar". Visual Studio se encargará de la descarga y la instalación en su nombre.

  

• NuGet instalará el paquete IronPDF junto con cualquier dependencia necesaria para su proyecto.
• Tras la instalación, IronPDF puede utilizarse para su proyecto.

Instalación a través del sitio web de NuGet

Para obtener más información sobre las características de IronPDF, su compatibilidad y las descargas disponibles, visite su página en https://www.nuget.org/packages/IronPdf en el sitio web de NuGet.

Utilizar DLL para instalar

Como alternativa, puede integrar directamente IronPDF en su proyecto utilizando su archivo DLL. Para descargar el archivo ZIP que contiene la DLL, haga clic aquí enlace. Descomprima el archivo y añada la DLL a su proyecto.

Aplicación de la lógica

En el proceso de integración interviene la siguiente lógica:

1. Crear documentación con DocFX: Para empezar, utilice DocFX para crear su documentación. Para generar documentación HTML, es necesario ejecutar el proceso de creación de DocFX en el código fuente y los archivos Markdown del proyecto.

2. Utilice IronPDF para convertir la documentación HTML a PDF: Una vez creada la documentación HTML, utilice IronPDF para convertirla mediante programación a formato PDF. Convertir texto HTML en documentos PDF imprimibles es fácil con las funciones de conversión de HTML a PDF de IronPDF.

3. Automatizar el proceso de conversión: Utilizar código C# o scripts para automatizar el proceso de conversión y optimizar el flujo de trabajo. Esto garantiza que, si es necesaria la intervención manual, la documentación pueda actualizarse y regenerarse fácilmente.

using IronPdf;
        var Renderer = new IronPdf.HtmlToPdf();
        var PDF = Renderer.RenderUrlAsPdf("http://localhost:8080/index.html");
        // Save PDF to file
        PDF.SaveAs("output.pdf");
        Console.WriteLine("PDF generated successfully!");
        Console.ReadKey();

using IronPdf;
        var Renderer = new IronPdf.HtmlToPdf();
        var PDF = Renderer.RenderUrlAsPdf("http://localhost:8080/index.html");
        // Save PDF to file
        PDF.SaveAs("output.pdf");
        Console.WriteLine("PDF generated successfully!");
        Console.ReadKey();

Imports IronPdf
		Private Renderer = New IronPdf.HtmlToPdf()
		Private PDF = Renderer.RenderUrlAsPdf("http://localhost:8080/index.html")
		' Save PDF to file
		PDF.SaveAs("output.pdf")
		Console.WriteLine("PDF generated successfully!")
		Console.ReadKey()

Para más información sobre el ejemplo de código, consulte este enlace. A continuación se muestra el resultado de la ejecución:

Conclusión

Por último, los desarrolladores disponen de una sólida opción para crear y difundir excelente documentación en formato PDF mediante la integración de DocFX con IronPDF en C#. Los desarrolladores pueden producir una amplia documentación lista para su uso fuera de línea a la que se puede acceder y compartir fácilmente combinando las funciones de producción de PDF de DocFX e IronPDF para la generación de documentación. Los proyectos de software salen adelante con más frecuencia gracias a esta integración, que también mejora el flujo de trabajo de documentación y hace que la documentación del proyecto sea más fácil de leer y accesible.

Los desarrolladores pueden optimizar sus procedimientos de documentación, mejorar el trabajo en equipo y la comunicación, y ofrecer mejores experiencias de documentación a los usuarios y partes interesadas aplicando las recomendaciones de este artículo y haciendo uso de las capacidades de DocFX e IronPDF.

El paquete Lite, de 749 dólares, incluye una licencia perpetua, un año de mantenimiento del software y una actualización de la biblioteca. IronPDF ofrece licencias gratuitas con restricciones de redistribución y temporales. Los usuarios pueden evaluar la solución durante el periodo de prueba sin tener que ver una marca de agua. Para obtener información adicional sobre el precio y la licencia, consulte la licencia de IronPDF página. Ir a página para obtener información adicional sobre las bibliotecas de Iron Software.