کدینگ کاگز

Sphinx

در این مثال یک صفحه ی داکیومنتیشن html ایجاد میکنیم. از کد تابع is_divisible در مثال 113 استفاده خواهیم کرد و سپس با ابزار sphinx داکیومنتیشن تحت وب خود را ایجاد میکنیم:

1-یک دایرکتوری جدید ایجاد کرده و divisible.py و یک دایرکتوری به نام docs در آن ایجاد کنید. محتوای divisible.py به صورت زیر است:

def is_divisible(x, y):
    if x % y == 0:
        return True
    else:
        return False

2- ابتدا sphinx را به صورت global (بدون محیط مجازی) نصب کنید:

python –m pip install sphinx -user

سپس از طریق ترمینال وارد docs شوید و دستور زیر را اجرا کنید:

$ cd docs

$ sphinx-quickstart

در ادامه اطلاعات ضروری را وارد کنید:

Project name: codingcogs_divisible Author name: Soroush Project Release: 1.8.0 Autodoc: y Intersphinx: y

با وارد کردن این موارد یک خروجی HTML برای شما ایجاد می شود. دو مورد آخر یعنی autodoc برای ما documentation را بر اساس کد تولید می کند و intersphinx نیز اجازه ی documentation پکیج های رسمی پایتون(یا هر پروژه ی دیگری که دارای sphinx است) در کنار برنامه ی خود را به شما می دهد.

3- با توجه به سیستم عامل خود یکی از دستورات زیر را در ترمینال در دایرکتوری docs اجرا کنید:

# windows
./make.bat html

# unix(mac & linux)
Makefile html

پس از این در آدرس docs/_build/html برای شما یک سری فایل ایجاد می شود. فایل index.html در مرورگر خود باز کنید. در خروجی میبینید:

حال اگر قصد داشته باشیم این صفحه را درست کنیم میتوانیم کارهای مختلفی انجام دهیم.

4- فایل conf.py ایجاد شده در فولدر docs را باز کنید و 3 خط زیر را uncomment کنید و خط سوم را به شکل کد پایین تغییر دهید :

# from
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# to
import os
import sys
sys.path.insert(0, os.path.abspath('..'))

دو نقطه به معنی بازگشت به دایرکتوری parent دایرکتوری docs است؛ یعنی آنجایی که کد اصلی تابع ما قرار دارد. در کنار این مسئله Napoleon را نیز به تنظیمات extensions در conf.py اضافه کنید. این کار را با استفاده از راهنمای دایکیومنتیشن انجام دهید:

https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

5- به فایل index.rst دو خط زیر را اضافه کنید تا داکیومنتیشن از سورس کد تولید شود

automodule:: divisible
:members:

بعد از این مرحله دوباره دستور make html را اجرا کنید تا مطمئن شوید که پیغام خطایی نمیبینید. اگر پیغام خطایی مشاهده کردید مراحل را مجددا بررسی کنید تا مطمئن شوید درست عمل کرده اید و داکیومنتیشن sphinx را بخوانید.

6- درون فایل divisible.py در بخش های مختلف docstring های مختلفی را به شکل زیر اضافه کنید:

'''Functions to work with divisibles'''
def is_divisible(x, y):
    '''Checks if a number is divisible by another
    Arguments:
        x (int): Divisor of the operation.
        y (int): Dividend of the operation.
    Returns:
        True if x can be divided by y without reminder,
        False otherwise.
    Raises:
        :obj:'ZeroDivisionError' if y is 0.
    '''
    if x % y == 0:
        return True
    else:
        return False

به ساختار بالا napoleon style syntax گفته می شود که آن را به conf.py اضافه کرده اید. دستور make html را مجددا اجرا کنید و بعد دوباره فایل index.html را باز کرده و باید ببینید:

این فایل را به عنوان یک سایت استاتیک میتوانید دیپلوی کنید!