Загадката на сфинкса: Как лесно да документираме кода си

Снимка на Даниел Х. Тонг на Unsplash

Защо съм тук?

Вие, читателят, сте тук, защото написахте страхотен инструмент в Python и искате да го направите достъпен и лесен за използване.

Аз, писателят, съм тук, защото бях точно там, където сте преди няколко месеца. Исках да използвам пакета Sphinx, за да направя документация в стила на ReadTheDocs за моя проект.

Открих вграждането на нетривиално Sphinx, поради което направих това репо за GitHub, което може да се използва като шаблон за вашия проект.

Преди да започнем, няколко основни предположения, за да сме сигурни, че сме на една и съща страница:

  • Пишете в Python.
  • Написахте документи за частите от кода, които искате да документирате.
  • Вашата цел е да направите документация в стил ReadTheDocs, която, поне частично, автоматично ще се генерира автоматично.
  • Наясно сте, че след 10 минути бихте могли да публикувате първата версия на документацията си, която ще изглежда така:

Част 1 - Настройка на сцената

  • Инсталиране на Sphinx: пип инсталирате сфинкс
  • Отидете на github.com/DalyaG/Sphinx185:
  • Изтеглете документацията на папката_template_for_your_next_project
  • Копирайте в проекта си
  • Преименувайте документацията на папката

Част 2 - Персонализиране

  • Отворете файла /documentation/conf.py в любимия си редактор. Потърсете модел # CHNAGEME # и следвайте инструкциите.
  • По подобен начин редактирайте файла /documentation/index.rst и следвайте вградените инструкции.

Част 3 - Добавете желаното от вас съдържание

  • Да речем, че имате файл с питон, наречен my_amazing_class.py, който включва клас, който искате да документирате.
  • В същата папка като файловете conf.py и index.rst създайте нов файл, наречен my_amazing_class.rst и копирайте-поставете персонализирайте този шаблон:
Това е шаблон за включване на класове
========================================
|

.. автоклас :: my_amazing_class.MyAmazingClass

|

: ref: `Върнете се у дома `
СЪВЕТ: уверете се, че папката, съдържаща вашия невероятен клас, е във вашия PYTHONPATH и че включва init file__init__.py
  • Във файла index.rst редактирайте съдържанието, за да включите името на .rst файла:
.. toctree ::
   : maxdepth: 1
   : име: mastertoc
   my_amazing_class

Част 4 - „Съставяне“

  • В терминала, вътре в папката с документацията, стартирайте, направи чист html.
  • Това е! Имате готов за преглед първата си версия на документацията!
  • Отворете документацията на файла / _build / html / index.html във вашия браузър и се уверете сами :)

Част 5 - Домакин на страниците на GitHub

  • Под корен на вашия проект отворете нова папка, наречена документи и копирайте вътре в нея съдържанието на / документацията / _build / html /
  • Вътре в тази нова папка с документи създайте празен файл, наречен .nojekyll
    (Това казва на GitHub Pages да заобикалят стандартните теми на Jekyll и да използват HTML и CSS във вашия проект)
  • Избутайте промените си към главния клон.
  • В хранилището си в GitHub, отидете на Settings-> GitHub Pages-> Source
    и изберете главна папка клонове / документи

Част 6 - Споделете!

Мда. Това е. Изчакайте няколко минути, за да се актуализира GitHub. Споделете вашия красив сайт с документация на

HTTPS: // .github.io / /

СЪВЕТ: Когато актуализирате документацията, трябва да изтриете папката с документи и да я създадете отново. Вижте повече подробности тук.

епилог

Това е частта, в която казвам нещо замислено за това колко прекрасно е да създавате ново съдържание в света. И какъв прекрасен човек сте, че сте избрали да направите оригиналното си съдържание достъпно, достъпно и лесно за използване.

Но ей, стигнахте дотук, така че вече знаете тези неща.

Така че ако има още нещо, което все още чувствате, че не знаете, аз ви каня да разгледате уебсайта с документацията, който направих за този урок. Можете да гледате беседата, която изнесох за Сфинкса. Надяваме се, че те ще отговорят на някои гатанки, които сте оставили за Сфинкса.