وبلاگ محمود امین طوسی: تجربه‌ای با Sphinx

۱۳۸۹/۰۵/۰۶

تجربه‌ای با Sphinx

بروزرسانی صفخات وب یکی از معضلات من است. هر بار باید فایل HTML را باز نموده تغییراتی داده و آنرا آپلود نمایم. اگر فایل با میکروسافت ورد آماده شده باشد که حجم و متخلفات آن بسیار زیاد است. مدتی پیش برای آماده‌سازی صفحه وب مربوط به داده‌ها و پیاده‌سازیهای یکی از مقالاتم ترجیح دادم که آنرا به صورت دستی آماده نمایم تا با ورد. به این ترتیب حجم فایل بسیار کم شد. برای قرار دادن جداول لاتک مقاله‌ام هم یک اسکریپت SED نوشتم که کار بسی راحت شد.
در آن مورد کارم راه افتاد ولی این مشکل برای مستندسازی فایلهای یک پروژه وجود دارد. یکی از راههای انجام چنین کاری استفاده از reStructured Text و استفاده از ابزاری همچون Sphinx برای تبدیل آنها به HTML یا LaTeX است.
در جستو به این صفحه از سایت VanderLinden رسیدم که راهنمای خوبی در مورد تولید خودکار مستندات با استفاده از Mercurial, Sphinx, reStructured Text است. چون با راهنمایی‌های سایت مذکور به نتیجه رسیدم تصمیم گرفتم که آنرا در اینجا هم ذکر کنم. روش ذکر شده در آن در لینوکس است که من برخی مراحل را در اوبونتو چک کردم ولی تا آخر نرفتم. فقط یک نکته باید ذکر کنم که از آنجا که برخی از ملزومات اینکار در سورس‌فورج قرار دارد و نصب آنها در اوبونتو با مشکل مواجه می‌شود، باید آنها را جداگانه دانلود نمود و سپس نصب نمود. به نظرم بیشتر آنها با دستور خط فرمان python setup.py install نصب می‌شوند. فایلهای .egg‌هم با easy_install نصب می‌شوند. در ادامه به مراحل کار در ویندوز خواهیم پرداخت.
به فرض python روی سیستم شما نصب شده است.

نصب SPHINX، DOCUTILS و JINJA2
Sphinx، Docutils و Jinja2 را از سایتهای مربوطه دانلود و نصب نمایید.

نصب Mercurial
در مورد Mercurial قبلاً پستی داشته‌ام. آنرا نصب نمایید.

ایجاد یک مخزن
با دستور hg init mydox مخزنی به نام mydox ایجاد کنید. قرار است به محض commit کردن این مخزن، فایلهای HTMLی که بعداً ساخته می‌شوند به صورت خودکار و مبتنی بر فایلهای .rst بروزرسانی شوند. اکنون باید شاخه .hg را داشته باشید.
من برای تست mydox را در همان شاخه Sphinx ایجاد کردم.

پیکربندی SPHINX
با دستور python sphinx-quickstart پیکربندی انجام می‌پذیرد. برای نام پروژه، نام مؤلف و شماره نسخه مواردی را خودتان درنظر بگیرید؛ تنظیمات پیش‌فرض را قبول کنید و تا انتها ادامه دهید. اکنون باید شاخه‌های source,build ایجاد شده باشند.

ایجاد فایل RESTRUCTURED TEXT
فایل ReSTی که قرار است مثلاً به HTML‌تبدیل شود را در شاخه source ایجاد نمایید. به فرض این فایل با نام first_doc.rst و با محتویات زیر است:

=========================
This Is My First Document
=========================

Yes, this is my first document.  It's lame.  Deal with it.

اکنون با استفاده از دستور python ..\sphinx-build.py source/ docs می‌توان خروجی HTML فایل rst. را در شاخه mydox/docs داشت.

خودکارسازی تولید HTML در هنگام COMMIT
اگر خواسته باشیم در هنگام commit کردن تغییرات توسط Mercurial، به صورت خودکار فایلهای HTML بروزرسانی شوند باید از precommit hook در Mercurial استفاده نمود.
فایل mydox/.hg/hgrc را باز نمایید و خطوط زیر را به آن اضافه کنید (اگر این فایل نیست، ایجادش کنید):

[hooks]
precommit.sphinxify = MYDOXPATH\sphinxify_docs.bat

که در آن MYDOXPATH مسیر شاخه mydox است.
فایل sphinxify_docs.bat را با محتویات زیر در شاخه mydox ایجاد کنید:

cd MYDOXPATH

python ..\sphinx-build.py source/ docs/

حال اگر هر commitی در Mercurial انجام دهید، به شرطی که تغییری در فایلها داده باشید، HTML به صورت خودکار بروزرسانی خواهد شد:

> hg ci -m "Initial commit"

موارد دیگری هم در پست VanderLinden هست که می‌توانید به آن مراجعه نمایید. برای خودم که خیلی جالب بود، امیدورام برای شما هم مفید باشد.

به عنوان یک نمونه سایت که از Sphinx استفاده کرده است، سری به سایت http://www.mathjax.org بزنید.

هیچ نظری موجود نیست:

ارسال یک نظر

حدیث قدسی

اولین پست
امام صادق علیه السلام بیان نموده اند که خدای تعالی می فرماید:
" به عزت و جلال و بزرگواری و جایگاه مرتفع عرشم سوگند که امید هر کسی را که به جز من امیدوار باشد حتماً و حتماً به وسیلۀ نومیدی خواهم برید و لباس مذلت و خواری در نزد مردم را حتماً و حتماً به او خواهم پوشانید و او را از نزدیک شدن به بارگاهم حتماً و حتماً دور خواهم ساخت. آیا در سختی ها جز مرا آرزو می کند و حال آنکه سختی ها همه بدست من است و به جز من امید بسته؟ و با حلقه فکر در خانۀ غیر مرا می زند و حال آنکه کلید درهای بسته بدست من است و در خانۀ من بروی هرکس که مرا بخواند باز است و کیست آنکه در مصیبت هایش مرا آرزو کرد و من رشته اتصال او را با خودم در آن مصیبتها بریدم؟ و کیست آنکه در مقصودی که داشت امید به من بست و من امیدش را قطع کردم؟ نگهداری آرزوهای بندگانم را خودم بعهده گرفتم ولی آنان به نگهداری من راضی نشدند و آسمانهایم را از فرشتگانی که از تسبیح خوانی من ملامتی به خود راه نمی دهند پر کردم و دستورشان دادم که درهای میان من و بندگانم را نبندند ولی بندگانم به گفتۀ من اعتماد نکردند. آنکس که مصیبتی از مصیبتهایش شب هنگام بسراغش می آید مگر نمی داند که هیچ کس به جز من بر برطرف کردن آن مصیبت مالک نیست؟ آیا بندۀ من مرا چنین می بیند که من پیش از سؤال کردن آغاز عطا کنم سپس که از من سؤال کنند اجابتشان نکنم؟ مگر من بخیلم که بندۀ من مرا به بخل نسبت می دهد؟ مگر بخشایش و کرم از آن من نیست؟ مگر گذشت و رحمت بدست من نیست؟ مگر من محل آرزوها نیستم؟ پس چه کسی رشتۀ آرزوها را به جز من می تواند قطع کند؟ آنان که آرزومندانند مگر نمی ترسند که به جز من آرزو می بندند؟ اگر همۀ اهل آسمانهایم و اهل زمینم همگی آرزوها داشته باشند، آنگاه من به هر یک از آنها به اندازۀ همۀ آنچه همگی آرزو دارند بدهم به قدر ذره ای از ملک من کم نمی شود و چگونه ممکن است کم شود ملکی که من خودم قیم و برپادارندۀ آن هستم؟ ای بدا بحال آنان که از رحمت من ناامیداند و ای بدا به حال آنکه معصیت مرا بکند و احترام مرا نگاه ندارد."