یک نکتهی تکمیلی: استفادههای دیگر از github pages
+ روش ساخت راهنمای خودکار برای پروژههای کتابخانهای با استفاده از « docfx »
« docfx » امکان اسکن خودکار اسمبلیهای پروژهی شما و تبدیل XML Comments آنها به یک سایت استاتیک را دارد که میتوان در نهایت آنرا در Github pages، همانند نکاتی که در این مطلب مشاهده کردید، منتشر کرد. برای اینکار ابتدا باید ابزار CLI آنرا نصب کنید: dotnet tool update -g docfx
پس از نصب آن، اجرای دستور زیر، سبب تولید این سایت استاتیک میشود:
docfx docs/docfx.json --serve
یک نمونه از فایل docfx.json تنظیم شدهی برای خواندن کامنتهای یک پروژه را
در اینجا میتوانید مشاهده کنید که به همراه ذکر مسیر فایل csproj و سایر تنظیمات استاندارد docfx است (و اگر خواستید یک نمونهی خالی آنرا ایجاد کنید، دستور docfx init -q -o docs
را صادر کنید). دستور فوق سبب میشود تا کار خودکار build پروژه و ساخت سایت استاتیک، در پوشهی
docs/_site انجام شود و همچنین server-- آن امکان دسترسی به سایت را در مسیر http://localhost:8080
میسر میکند (برای آزمایش و بررسی local). سپس نیاز است تا این پوشه به صورت github pages در دسترس قرار گیرد. برای اینکار فقط کافی است چند سطر زیر را به تنظیمات github actions خود اضافه کنید تا به ازای هر تغییری در کدها، این توزیع به صورت خودکار انجام شود: - run: dotnet tool update -g docfx
- run: docfx docs/docfx.json
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: docs/_site
با اینکار یک branch جدید به نام gh-pages ایجاد خواهد شد که پوشهی docs/_site را در اختیار github pages قرار میدهد. یعنی مطابق نکاتی که در قسمت فعال سازی github pages مطلب جاری مشاهده کردید، باید به قسمت settings->pages در github مراجعه کرده و source را بر روی
نام شاخهی جدید gh-pages قرار داده و آنرا
ذخیره کنید. همین مقدار تنظیم جهت آماده شده دسترسی به راهنمای تولید شده به صورت
یک سایت استاتیک، کفایت میکند.