Python layihənizi Sphinx və Rinohtype ilə sənədləşdirmək üçün sadə bir təlimat

Kod sənədləşdirmək həqiqətən etmək istəmədiyim şeylərdən biridir, amma hər halda sinif səviyyələri üçün edəcəyəm.

Yəqin ki, birinci ilində kompüter elmləri öyrənəndə bunu məndən eşidəcəksiniz. Kodun sənədləşdirilməsini darıxdırıcı və faydasız hesab etdim, çünki onsuz da kodumun nə etdiyini bilirəm və oxumağı ehtimal edən tək adam onu ​​nəzərdən keçirən professordur.

Bir il əvvəl istinad üçün yazdığım sənədsiz koda baxdığım bir günə qədər mənasını anlamadım və sadəcə onu nəzərdən keçirmək əvəzinə, layihəni necə qurduğumdan və hətta hətta çox qarışıq olduğumdan çox vaxt sərf etdim necə işlədiləcək.

Bu günlərdə kodu sənədləşdirməyimizə kömək edəcək bir çox vasitə var. Bu yaxınlarda ağıllı və cəlbedici sənədlər yaratmağı asanlaşdıran vasitələrlə tanış oldum. Onlardan ikisi Sfenks və Rinohtaypdır.

Georg Brandl tərəfindən yazılmış və BSD lisenziyası ilə lisenziyalı Sfenks, əvvəlcə Python sənədləri üçün hazırlanmışdır və müxtəlif dillərdə proqram layihələrini sənədləşdirmək üçün əla seçimlərə malikdir (Sphinx-doc.org, 2018).

Sfenks ilə qoşulan Rinohtype, LaTeX-ə müasir bir alternativ təklif edir. Professional şəkildə qurulmuş PDF sənədləri (Machiels) yaratmaq üçün istifadə edə biləcəyiniz bir Sfenks arxa tərəfi təqdim edir.

Bu dərsdə müəllim qeydlərinin siyahısını (Github Project Link) saxlayan sadə bir API layihəsi üçün HTML və PDF sənəd sənədləri yaratmaq üçün Sfenks və Rinohtype istifadə edirəm.

  1. Layihəni klonlaşdırın və sənədlər qovluğunu silin / köçürün ki, yeni sənədləri yaratdığım zaman məni izləyə bilərsiniz.
  2. Layihənin kök qovluğuna keçin.
  3. Python 3 virtual mühiti yaradın və aktivləşdirin
virtualenv -p python3 mənbə / bin / activate
Burada virtual mühitimə

4. Layihənin bütün tələblərini quraşdırın

pip install -r requirements.txt

Qeyd: Sfenks və Rinohtype artıq requirements.txt faylındadır. Onları hazırda işlədiyiniz layihənin virtual mühitində quraşdırmaq istəyirsinizsə, aşağıdakı əmrlərdən istifadə edin.

Pip Sphinx pip install rinohtype quraşdırın

5. Docs qovluğu yaradın və bu qovluğa CD yerləşdirin.

mkdir sənədləri CD sənədləri

6. Sfenks qurun

Sfenks sürətli başlanğıc
Hələlik bu konfiqurasiyaya əməl edin. Bunu daha sonra özünüz yenidən qura bilərsiniz.Əvvəlki şəklin davamı

7. Açıq mənbə / conf.py

  • Kök qovluğuna gedən yolu konfiqurasiya edin
Şərh sətirləri 15-17Yolu

Yol layihənin kök qovluğuna işarə etməli və layihə quruluşunu göstərməlidir. Conf.py-dən iki ana qovluğa gedərək kök qovluğuna çatmalıyıq.

Layihə quruluşu
  • Uzantılar siyahısına Rinohtype əlavə edin
'rinoh.frontend.sphinx'
  • Lateks elementlərini şərh edin
Bunu şərh edinFormatı daha da dəyişə bilərsiniz, bunlar yalnız standart parametrlərdir.

8. index.rst faylını açın və məzmunu aşağıdakı kimi dəyişdirin. (Bütün məzmununa baxmaq üçün index.rst linkini vurun.)

Kod üçün sənədlər ************************** .. toctree ::: maxdepth: 2: caption: Contents: TeacherAPI main ===== ============= .. automodule :: app: Üzvlər: TeacherAPI-Controller ===================== .. avtomat modu :: teacherAPI.controller: üzvləri: TeacherAPI modelləri ================== .. avtomodule :: teacherAPI.models: üzvləri: TeacherAPI verilənlər bazası ========== ======== .. automodule :: teacherAPI.database: Üzvlər: TeacherAPI doldurulur =================== .. automodule :: teacherAPI.populate: Members :

9. HTML və PDF sənədləri sənədlərini yaradın.

  • Hələ də sənədlər qovluğunda işləyir
HTML sphinx-build -b rinoh mənbə _build / rinoh edir

DİQQƏTİ RƏHD EDİN [16. Mart 2019]: Python versiyanız ≥3.7.0 olduqda (Github probleminə istinad) PDF sənədinin yaradılması uğursuz olur

Birinci sətir HTML sənədini docs / build / html / index.html-də yaradır

İndex.html görünüşüİndex.html görünüşü

İkinci sətirdə PDF faylı sənədlərdə yaradılır / _build / rinoh / SimpleTeacherDataAPI.pdf

Sənədləşmə örtüyüMündəricatSənədlərin nümunə səhifəsi

Komanda layihələrində təcrübə qazandıqdan sonra kodu necə sənədləşdirəcəyimi anlamağa başladım. Ən əyləncəli tapşırıq olduğunu söyləməsəm də, mütləq etibarlıdır və proqramçılar tərəfindən edilməlidir tətbiq olunmaq.

Sfenks haqqında daha çox məlumat üçün:

  • Baxış - Sfenks 1.8.0+ üçün sənədlər

Digər faydalı dərsliklər:

  • Sfenksdən istifadə edərək layihənizi sənədləşdirmək - Bu, Python sənədlərindən istifadə edərək kodumu necə sənədləşdirəcəyimi anlamağa kömək etdi.
  • Brandon's Sphinx Tutorial - Sfenksdən necə istifadə olunacağına dair hərtərəfli təlimat

Machiels, Brecht. "Rinohtype: Python Document Processor - Rinohtype 0.3.1.Dev0 Documentation." Rinohtype.readthedocs.io. Np, 2016. Veb. 17 iyun 2018.

Sphinx-doc.org. (2018). Baxış - Sfenks 1.8.0+ üçün sənədlər. [onlayn] Mövcuddur: http://www.sphinx-doc.org/en/master/ [17 iyun 2018-ci ildə daxil olmuşdur].