بروزرسانی صفخات وب یکی از معضلات من است. هر بار باید فایل 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 ایجاد کنید:

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

> hg ci -m "Initial commit" 

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