Tutorial Mudah tentang Cara mendokumenkan Projek Python anda menggunakan Sphinx dan Rinohtype

Kod dokumentasi adalah salah satu tugas yang saya tidak mahu lakukan, tetapi saya akan melakukannya untuk gred.

Ini mungkin yang anda akan dengar daripada saya ketika saya adalah pelajar sains komputer tahun pertama. Saya mendapati dokumen yang membosankan dan tidak berguna kerana saya sudah tahu apa kod saya lakukan dan satu-satunya orang yang mungkin akan membacanya ialah profesor menyemaknya.

Saya tidak faham kepentingannya sehinggalah suatu hari, saya perlu melihat kod tanpa kod yang saya tulis bertahun-tahun yang lalu untuk rujukan dan bukannya sekadar memilikinya, saya menghabiskan banyak masa yang agak keliru tentang bagaimana saya menstrukturkan projek dan bahkan bagaimana untuk menjalankannya.

Hari ini, terdapat banyak alat yang tersedia untuk membantu kami mendokumentasikan kod. Baru-baru ini, saya mempelajari alat yang membuatnya mudah untuk membuat dokumentasi pintar dan indah. Dua daripada mereka adalah Sphinx dan Rinohtype.

Sphinx, yang ditulis oleh Georg Brandl dan dilesenkan di bawah lesen BSD, pada asalnya dicipta untuk dokumentasi Python dan ia mempunyai kemudahan yang sangat baik untuk dokumentasi projek perisian dalam pelbagai bahasa (Sphinx-doc.org, 2018).

Rinohtype, dipasangkan dengan Sphinx menawarkan alternatif moden kepada LaTeX. Ia menyediakan backend Sphinx yang membolehkan menghasilkan generates dokumen PDF dokumen (Machiels).

Dalam tutorial ini, saya akan menggunakan Sphinx dan Rinohtype untuk menghasilkan fail dokumentasi HTML dan PDF masing-masing kepada projek API mudah yang saya tulis yang menguruskan senarai rekod Guru (Github Project Link).

  1. Clone projek dan padam / pindahkan folder docs supaya anda boleh mengikuti saya dalam membuat dokumentasi baru.
  2. Pergi ke direktori akar projek.
  3. Buat dan aktifkan persekitaran maya Python 3
virtualenv -p python3 
sumber  / bin / aktifkan
Di sini saya menamakan persekitaran maya saya 'venv'

4. Pasang semua keperluan projek

paip memasang -r requirements.txt

Nota: Sphinx dan Rinohtype sudah berada di dalam fail requirements.txt. Jika anda ingin memasangnya dalam persekitaran maya projek yang anda sedang gunakan untuk menggunakan arahan berikut.

pip memasang Sphinx
paip memasang rinohtype

5. Buat direktori doc dan cd ke direktori ini.

mkdir docs
cd docs

6. Persediaan Sphinx

sphinx-quickstart
Ikut konfigurasi ini sekarang. Anda boleh menyusun semula ini kemudian anda sendiri.kesinambungan gambar terdahulu

7. Buka sumber / conf.py

  • Konfigurasikan laluan ke direktori root
Garis undikan 15-17Ubah laluan ke '../ ..' dan Tambah sys.setrecursionlimit (1500)

Jalan harus menunjuk pada direktori akar projek dan melihat struktur projek, dari conf.py kita harus mencapai akar dengan naik dua direktori induk.

Struktur projek
  • Tambah Rinohtype ke senarai pelanjutan
'rinoh.frontend.sphinx'
  • Uncomment unsur-unsur lateks
jangan komen iniAnda boleh menukar format selanjutnya, ini hanya lalai.

8. Buka index.rst dan tukar kandungan kepada yang berikut. (Klik pautan index.rst untuk kandungan penuh)

Dokumentasi untuk Kod
**************************
.. toctree ::
   : maxdepth: 2
   : kapsyen: Kandungan:

TeacherAPI utama
===================
.. automodule :: app
   : ahli:

Pengawal TeacherAPI
=====================
.. automodule :: teacherAPI.controller
   : ahli:

Model TeacherAPI
=================
.. automodule :: teacherAPI.models
   : ahli:

Pangkalan data TeacherAPI
===================
.. automodule :: teacherAPI.database
   : ahli:

TeacherAPI tinggal
===================
.. automodule :: teacherAPI.populate
   : ahli:

9. Buat fail dokumentasi HTML dan PDF.

  • Masih di dalam direktori docs dijalankan
membuat html
sphinx-build -b rinoh source _build / rinoh

EDIT NOTA [16 Mac, 2019]: Membina fail pdf akan gagal jika versi Python anda adalah ≥3.7.0 (rujukan isu Github)

Baris pertama akan menghasilkan fail HTML dalam dokumen / bina / html / index.html

Pandangan dari index.htmlPandangan dari index.html

Baris kedua akan menghasilkan fail PDF dalam docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Halaman tajuk dokumentasiIsi kandunganHalaman sampel dokumentasi

Selepas mengalami projek-projek pasukan, saya mula membangun penghargaan dalam mendokumentasikan kod dan walaupun, saya tidak akan mengatakan ia adalah tugas yang paling menyeronokkan, ia pasti boleh dipercayai dan harus diamalkan oleh pengaturcara .

Untuk mengetahui lebih lanjut mengenai Sphinx:

  • Gambaran Keseluruhan - dokumentasi Sphinx 1.8.0+

Tutorial berguna lain:

  • Mendokumentasikan Projek Anda Menggunakan Sphinx - Ini membantu saya memahami bagaimana untuk mendokodkan kod saya menggunakan pempstruktur Python.
  • Tutorial Sphinx Brandon - Tutorial luas menggunakan Sphinx

Machiels, Brecht. "Rinohtype: Pemproses Dokumen Python - Dokumentasi Rinohtype 0.3.1.Dev0." Rinohtype.readthedocs.io. N.p., 2016. Web. 17 Jun 2018.

Sphinx-doc.org. (2018). Gambaran Keseluruhan - dokumentasi Sphinx 1.8.0+. [online] Boleh didapati di: http://www.sphinx-doc.org/en/master/ [Diakses pada 17 Jun 2018].