W dzisiejszym środowisku tworzenia oprogramowania jasna i wyczerpująca dokumentacja ma kluczowe znaczenie dla zapewnienia sukcesu projektu. DocFX C# i IronPDF to dwa skuteczne narzędzia, które generują dokumentację oraz poprawiają czytelność i dostępność dokumentacji projektowej, jednocześnie usprawniając procesy tworzenia dokumentacji. W tym poście wyjaśnimy, jak połączyć IronPDF, bibliotekę C# do tworzenia dokumentów PDF, z DocFX, generatorem dokumentacji API, który tworzy Dokumentację API. Dzięki tym narzędziom programiści mogą szybko tworzyć doskonałą dokumentację i udostępniać ją w formacie PDF.

Jak korzystać z DocFX

1. Zainstaluj .NET SDK 6.0+
2. Otwórz PowerShell.
3. Uruchom skrypty jeden po drugim, aby zainstalować bibliotekę DocFX.
4. Po instalacji uruchom plik JSON.
5. Spowoduje to otwarcie strony dokumentacji na porcie 8080.

Wprowadzenie do DocFX

Firma Microsoft stworzyła DocFX — otwarte oprogramowanie do generowania statycznych stron internetowych oraz dokumentacji. Korzystając z plików Markdown i kodu źródłowego, programiści mogą tworzyć strony internetowe z dokumentacją, które wyglądają profesjonalnie. DocFX jest elastyczny i ma szerokie zastosowanie w różnych projektach, ponieważ obsługuje wiele formatów znaczników i języków programowania.

Programiści mogą tworzyć samouczki, artykuły koncepcyjne i Dokumentację API w swojej dokumentacji, korzystając z DocFX. Dzięki elastycznej architekturze zespoły mogą dostosowywać i rozszerzać ją, aby spełnić swoje unikalne wymagania. DocFX oferuje również funkcje takie jak odsyłacze, edytowalne szablony oraz obsługę kilku formatów wyjściowych, w tym HTML i Markdown. Aby uzyskać bardziej szczegółowy opis wewnętrznego działania i metod DocFX, odwiedź dokumentację DocFX.

Pierwsze kroki z DocFX

Konfiguracja DocFX

Korzystanie z DocFX jest dość proste. Wymaga to dodania zestawu DocFX SDK przy użyciu menedżera pakietów .NET firmy Microsoft, NuGet. Biblioteki i narzędzia wymagane do włączania treści internetowych do aplikacji przy użyciu DocFX są zawarte w tym pakiecie SDK.

Utwórz nową stronę internetową DocFX

W tej fazie stworzymy podstawową stronę internetową z dokumentacją na Twoim komputerze.

• Konieczna jest podstawowa znajomość obsługi wiersza poleceń.
• Wymagana jest wersja .NET SDK 6.0 lub nowsza.

Aby zainstalować najnowszą wersję DocFX, upewnij się, że masz zainstalowany pakiet .NET SDK, a następnie otwórz narzędzie wiersza poleceń terminala i wpisz następujące polecenie:

dotnet tool update -g docfx

Aby utworzyć nowy zestaw dokumentów, należy wykonać:

docfx init

docfx init

Tworzy plik JSON zawierający wszystkie konfiguracje. Za pomocą tego polecenia można utworzyć nowy projekt DocFX w bieżącym katalogu roboczym. Aby utworzyć zestaw dokumentów, należy wykonać:

docfx docfx.json --serve

docfx docfx.json --serve

Strona internetowa jest teraz dostępna do podglądu na http://localhost:8080.

Zapisz zmiany. DocFX konfiguruje się za pomocą pliku konfiguracyjnego JSON. Teraz używamy nowego terminala, aby wykonać to polecenie w celu przebudowy strony internetowej i podglądu lokalnych zmian:

docfx docfx.json

docfx docfx.json

Funkcje DocFX

Elastyczny i rozszerzalny

DocFX jest kompatybilny z wieloma formatami znaczników i językami programowania, takimi jak pliki JSON, YAML i Markdown. Dzięki tej elastyczności zespoły mogą wybrać format, który najlepiej odpowiada ich wymaganiom i preferencjom. Ponadto rozszerzalna architektura DocFX pozwala programistom na dodawanie i modyfikowanie jego funkcji za pomocą wtyczek i szablonów, spełniając różnorodne potrzeby w zakresie dokumentacji.

Generowanie dokumentacji API

DocFX to doskonałe narzędzie, które pomaga tworzyć dokumentację API na podstawie komentarzy znalezionych w kodzie źródłowym. DocFX automatycznie tworzy Dokumentację API, w tym przestrzenie nazw, klasy, metody, parametry i typy zwracanych wartości, poprzez analizę komentarzy w kodzie w powszechnie używanych formatach, takich jak XML i YAML. Ta funkcja pozwala programistom zaoszczędzić mnóstwo czasu i wysiłku, usprawniając proces dokumentacji interfejsów API kodu.

Kompatybilność międzyplatformowa

Ponieważ DocFX jest wielopłatformowy, może działać w systemach Linux, macOS i Windows. Niezależnie od systemu operacyjnego używanego przez zespół programistów, ta kompatybilność międzyplatformowa gwarantuje, że generowanie dokumentacji można łatwo włączyć do różnych procesów i środowisk programistycznych.

Wbudowana wyszukiwarka i nawigacja

DocFX oferuje zintegrowaną obsługę nawigacji i wyszukiwania w wygenerowanej dokumentacji. Szybki dostęp do istotnych informacji jest możliwy dzięki możliwości łatwego wyszukiwania w dokumentacji tematów, interfejsów API lub słów kluczowych. Aby jeszcze bardziej zwiększyć użyteczność i poprawić wrażenia użytkownika, DocFX tworzy również spis treści (TOC), który ułatwia użytkownikom poruszanie się po hierarchii dokumentacji.

Integracja DocFX z IronPDF

Łącząc DocFX z IronPDF, programiści mogą wykorzystać zalety każdego z tych narzędzi i usprawnić proces tworzenia dokumentacji. Programiści mogą zapewnić spójne wyświetlanie na różnych urządzeniach, tworzyć dokumentację gotową do użycia w trybie offline oraz ułatwić udostępnianie i dystrybucję, wykorzystując IronPDF do konwersji dokumentacji HTML wygenerowanej przez DocFX do formatu PDF. Aby dowiedzieć się więcej o IronPDF, zapoznaj się z dokumentacją IronPDF.

Zainstaluj IronPDF

• Uruchom projekt Visual Studio.
• Wybierz "Narzędzia" > "Menedżer pakietów NuGet" > "Konsola menedżera pakietów".
• W konsoli menedżera pakietów Visual Studio wpisz następujące polecenie (popraw tę linię na właściwe polecenie instalacji pakietu):

Install-Package IronPdf

• Alternatywnie można zainstalować IronPDF za pomocą menedżera pakietów NuGet dla rozwiązań.

• Możesz wybrać pakiet IronPDF z wyników wyszukiwania, a następnie kliknąć opcję "Zainstaluj". Visual Studio zajmie się pobraniem i instalacją w Twoim imieniu.

  

• NuGet zainstaluje pakiet IronPDF wraz ze wszystkimi zależnościami wymaganymi dla Twojego projektu.

• Po instalacji IronPDF można wykorzystać w swoim projekcie.

Zainstaluj za pośrednictwem strony internetowej NuGet

Aby uzyskać dodatkowe informacje na temat funkcji, kompatybilności i dostępnych plików do pobrania IronPDF, odwiedź stronę pakietu NuGet na stronie internetowej NuGet.

Wykorzystaj bibliotekę DLL do instalacji

Alternatywnie można bezpośrednio zintegrować IronPDF z projektem, korzystając z pliku DLL. Aby pobrać plik ZIP zawierający bibliotekę DLL, należy kliknąć tę stronę pobierania biblioteki DLL. Rozpakuj plik i dodaj bibliotekę DLL do swojego projektu.

Wdrażanie logiki

W procesie integracji stosowana jest następująca logika:

1. Tworzenie dokumentacji za pomocą DocFX: Aby rozpocząć, użyj DocFX do stworzenia swojej dokumentacji. Aby wygenerować dokumentację HTML, należy uruchomić proces kompilacji DocFX na kodzie źródłowym i plikach Markdown projektu.
2. Użyj IronPDF do konwersji dokumentacji HTML do formatu PDF: Po utworzeniu dokumentacji HTML użyj IronPDF, aby programowo przekonwertować ją do formatu PDF. Konwersja tekstu HTML do dokumentów PDF nadających się do druku jest łatwa dzięki funkcjom konwersji HTML na PDF w IronPDF.
3. Zautomatyzuj proces konwersji: Użyj kodu C# lub skryptów, aby zautomatyzować proces konwersji i zoptymalizować przepływ pracy. Gwarantuje to, że dokumentacja może być łatwo aktualizowana i odtwarzana, jeśli nie jest wymagana ręczna interwencja.

using IronPdf;

class Program
{
    static void Main()
    {
        // Create a new HtmlToPdf Renderer
        var Renderer = new HtmlToPdf();

        // Render the webpage as PDF
        var PDF = Renderer.RenderUrlAsPdf("http://localhost:8080/index.html");

        // Save PDF to a file
        PDF.SaveAs("output.pdf");

        // Inform the user of successful PDF creation
        Console.WriteLine("PDF generated successfully!");
        Console.ReadKey();
    }
}

using IronPdf;

class Program
{
    static void Main()
    {
        // Create a new HtmlToPdf Renderer
        var Renderer = new HtmlToPdf();

        // Render the webpage as PDF
        var PDF = Renderer.RenderUrlAsPdf("http://localhost:8080/index.html");

        // Save PDF to a file
        PDF.SaveAs("output.pdf");

        // Inform the user of successful PDF creation
        Console.WriteLine("PDF generated successfully!");
        Console.ReadKey();
    }
}

Imports IronPdf

Friend Class Program
	Shared Sub Main()
		' Create a new HtmlToPdf Renderer
		Dim Renderer = New HtmlToPdf()

		' Render the webpage as PDF
		Dim PDF = Renderer.RenderUrlAsPdf("http://localhost:8080/index.html")

		' Save PDF to a file
		PDF.SaveAs("output.pdf")

		' Inform the user of successful PDF creation
		Console.WriteLine("PDF generated successfully!")
		Console.ReadKey()
	End Sub
End Class

Imports IronPdf

Friend Class Program
	Shared Sub Main()
		' Create a new HtmlToPdf Renderer
		Dim Renderer = New HtmlToPdf()

		' Render the webpage as PDF
		Dim PDF = Renderer.RenderUrlAsPdf("http://localhost:8080/index.html")

		' Save PDF to a file
		PDF.SaveAs("output.pdf")

		' Inform the user of successful PDF creation
		Console.WriteLine("PDF generated successfully!")
		Console.ReadKey()
	End Sub
End Class

Aby dowiedzieć się więcej o przykładowym kodzie, zapoznaj się z tym przewodnikiem po przykładowym użyciu. Poniżej przedstawiono wynik działania:

Wnioski

Wreszcie, programiści mają doskonałą możliwość tworzenia i rozpowszechniania doskonałej dokumentacji w formacie PDF poprzez integrację DocFX z IronPDF w języku C#. Programiści mogą tworzyć obszerną dokumentację gotową do użycia w trybie offline, która jest łatwo dostępna i można ją udostępniać, łącząc możliwości tworzenia plików PDF w DocFX i IronPDF w celu generowania dokumentacji. Ta integracja usprawnia proces tworzenia dokumentacji, poprawia jej czytelność i dostępność oraz zwiększa prawdopodobieństwo sukcesu projektu oprogramowania.

Programiści mogą zoptymalizować swoje procedury dokumentacyjne, usprawnić pracę zespołową i komunikację oraz zapewnić użytkownikom i interesariuszom lepsze doświadczenia związane z dokumentacją, wdrażając zalecenia zawarte w tym artykułe i wykorzystując możliwości DocFX oraz IronPDF.

Pakiet $999 Lite zawiera wieczystą licencję, roczne utrzymanie oprogramowania i aktualizację biblioteki. IronPDF oferuje bezpłatną licencję z ograniczeniami dotyczącymi redystrybucji i czasu. Użytkownicy mogą ocenić rozwiązanie w okresie próbnym bez konieczności oglądania znaku wodnego. Dodatkowe informacje na temat ceny i licencji można znaleźć w szczegółach licencyjnych IronPDF.