استفاده از Sphinx
استفاده از docstring ها برای داکیومنت کردن API(روابط کاربری برنامه ها، توابع و کلاس ها یا Application Programming Interface ) نسبتا کاربردی است ام در اکثر مواقع نیاز به چیزهای بیشتر و کامل تر و پیچیده تری وجود دارد. گاهی نیاز است یک وبسایت را به سرعت برای عرضه ی داکیومنت پکیج خود بالا بیاوریم؛ برای این کار در زبان پایتون راه های زیادی وجود دارد اما قدیمی ترین و یکی از کاملترین ابزار Sphinx است.
ابزار Sphinx به ما اجازه می دهد تا داکیومنتیشن کد خود را به صورت های PDF، epub یا html با استفاده از نوشتن markup در یک فایل RST به راحتی تولید کنیم. همچنین Sphinx با plugin ها و extension های مختلفی عرضه می شود که میتوانند تجربه ی تولید داکیومنتیشن را بهتر، ساده تر و موثر تر کنند.
این ابزار را به صورت گلوبال (خارج از محیط مجازی با دستور pip ) باید نصب کنید و پس از نصب در ترمینال خود به دو دستور sphinx-build و sphinx-quickstart دسترسی دارید. اولین دستور برای ساخت داکیومنتیشن و دومین دستور برای ساخت سریع قالب داکیومنتیشن کاربرد دارد.
3 فایل مهم در خروجی Sphinx وجود دارد که در کنار داکیومنتیشن توسط Sphinx تولید می شوند:
- فایل Conf.py : این فایل وظیفه ی پیدا کردن فایل های اصلی پروژه ی شما را به عهده دارد و در این فایل باید تنظیمات مربوط به پیدا کردن کد های خود را وارد کنید. در کنار این مسئله این فایل plugin ها و extension های مختلفی که نیاز داریم را نیز باید درون خود داشته باشد.
- فایل های Makefile : این فایل ها با پسوندهای مختلف برای سیستم عامل های مختلف اجازه ی ساخت سریع خروجی مورد نظر ما به عنوان داکیومنتیشن را می دهند. همچنین اجرای بی دلیل آنها به منظور بررسی تنظیمات Sphinx نیز بسیار رایج است(یعنی بعد از انجام تنظیمات مختلف الکی یک داکیومنتیشن می سازیم تا فقط مطمئن باشیم که کدهای اشتباهی را وارد تنظیمات Sphinx نکردیم ).
- فایل Index.rst : این فایل ورودی و ساختار استفاده از داکیومنتیشن در برنامه را مشخص می کند.
نمونه ی استفاده از Sphinx برای تولید داکیومنتیشن:
https://requests.readthedocs.io/en/latest/
در اکثر پروژه های متن باز به زبان های مختلف فولدری به نام docs وجود دارد که شامل داکیومنت های پروژه و فایل های ابزار تولید این داکیومنت هاست(مثل hf-doc-builder ،Aspose، sphinx ، ،Docbuilder).
برای آشنایی بیشتر با RST نیز به لینک زیر سری بزنید:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
به طور خلاصه RST به ما اجازه می دهد تا ساختارهای خاصی را به المان های HTML مثل links, anchors, tables, images تبدیل کنیم.
همچنین تم های زیادی نیز برای sphinx وجود دارند: