Искористите документе свог пројекта на најбољи начин—користите Спхинк за генерисање атрактивне, свеобухватне ХТМЛ документације.

Спхинк је један од најпопуларнијих алата за генерисање документације. Широм Питхон заједнице, програмери користе овај бесплатни софтвер отвореног кода. Може да извуче текст директно из вашег кода или мардовн датотека, а затим га користи за генерисање документације у различитим форматима као што су обичан текст, ХТМЛ, ПДФ и ЕПУБ.

Подешавање Сфинге

Пре него што подесите Спхинк, погледајте шта ради и неке од његових главних карактеристика.

Шта је Сфинга и шта ради?

Као што је поменуто, Спхинк је генератор документације. Подразумевано користи реСтруцтуредТект (РСТ) језик за означавање, али преко екстензија независних произвођача такође може користите Маркдовн, популарни језик за означавање обичног текста. Затим конвертује ове РСТ или мардовн датотеке у ХТМЛ, ПДФ, странице са упутствима или друге формате које желите.

Неке од карактеристика које Сфинга укључује су:

  • Способност генерисања документације из кода.
  • Способност унакрсног референцирања различитих страница докумената користећи аутоматске везе за функције, класе, цитате и термине у глосару.
  • Истицање синтаксе за блокове кода.
  • Подршка за теме које могу да промене изглед и осећај докумената.
  • Једноставна дефиниција стабла документа кроз садржај.
  • Могућност интеграције са екстензијама независних произвођача да бисте додали више функционалности документима као што су исечци кода за тестирање.

Инсталирање Спхинк

Пре инсталирања Спхинк, уверите се да јесте Питхон 3 инсталиран у вашем развојном окружењу. Затим можете користити пип менаџер пакета да инсталирате Спхинк тако што ћете покренути следећу команду у свом терминалу:

пип инсталл спхинк

Ово ће преузети и инсталирати Спхинк и његове зависности.

Након инсталације, покрените следеће на командној линији.

спхинк-буилд --верзија

Ако је све функционисало у реду, требало би да видите број верзије за пакет Спхинк који сте управо инсталирали.

Креирање новог пројекта Сфинга

Када инсталирате Спхинк, идите до свог радног директоријума и покрените команду спхинк-куицкстарт да бисте креирали нови пројекат Спхинк.

сфинга-брзи почетак

Ова команда ће од вас затражити да одговорите на низ питања о томе како да конфигуришете свој пројекат Спхинк. Можете одредити назив пројекта и користити подразумеване опције за друга питања. У будућности ћете можда желети да прилагодите одговоре на основу вашег пројекта.

Ако наведете садржај свог директоријума, видећете да ова команда креира неке датотеке за вас. цонф.пи садржи вредности конфигурације, а индек.рст служи као страница добродошлице ваше документације. Директоријум за изградњу ће угостити генерисану документацију, а Спхинк користи Макефиле (маке.бат на Виндовс-у) за прављење документације.

Писање документације користећи Спхинк

Датотека индек.рст у корену вашег директоријума је почетна страница ваше апликације. Дакле, отворите га помоћу уређивача текста као што је ВС Цоде—или било који други добар, бесплатни уређивач кода— да га уредите.

Можете променити индек.рст како вам одговара, али једна ствар коју би требало да има је корен тоцтрее (стабло садржаја) директива. Ово је неопходно јер повезује више датотека у једну хијерархију докумената.

Да бисте додали документацију у датотеку индек.рст, можете користити РСТ ознаке.

Као пример, размотрите датотеку индек.рст за модул матх_утилс. Ова датотека може укључивати кратак преглед сврхе модула и садржај који повезује са другим страницама документације.

Добродошли у Матх Утилс
.. тоцтрее::
 :макдептх: 2


Почетак


Да бисте користили овај модул, требаће вам следеће:


* Инсталиран Питхон.


* Уређивач текста


Матх Утилс


Модул `матх-утилс` пружа основне математичке функције као што су сабирање и
одузимање.

По потреби можете додати још .рст датотека. На пример, можете да креирате водич за доприносе у датотеци под називом цонтрибутинг.рст која садржи следеће смернице за доприносе.

Водич за доприносе
Поздрављамо доприносе нашем пројекту! Ево неколико смерница за
доприносећи:


- Форк пројекат на ГитХуб-у.
- Направите измене на новој грани.
- Напишите тестове да бисте били сигурни да ваше промене раде исправно.
- Пошаљите захтев за повлачење са вашим изменама.
- Направите све тражене измене.
Хвала вам на доприносу!

Затим можете повезати ову датотеку са индек.рст додавањем новог одељка у директиву тоцтрее:

.. тоцтрее::
 :макдептх: 2
 :цаптион: Садржај

 доприносећи

Ово креира нову ставку под називом допринос у табели садржаја која корисника води на страницу доприноса када се кликне.

Када напишете документацију, следећи корак је да је направите. Овде израда документације значи генерисање ХТМЛ, приручника или ПДФ страница из РСТ датотека.

Израда документације

Да бисте направили документацију користећи Спхинк, мораћете да покренете маке хтмл команду у корену фасцикле у којој се налази макефиле.

направи хтмл

Требало би да видите ХТМЛ датотеке у фасцикли за прављење. Ако је било грешака током изградње, Спхинк ће вас обавестити у терминалу.

Да бисте видели документацију, отворите датотеку индек.хтмл у свом претраживачу:

Требало би да можете да се крећете до водича за доприносе из табеле садржаја.

Прилагођавање документације

Тренутно, документација има неки основни стил. Ако желите да га прилагодите, можда додавањем боја вашег бренда, или чак додавањем тамног режима, можете да инсталирате и користите друге уграђене теме или креирајте сопствену прилагођену тему.

Да бисте демонстрирали, покушајте да промените тему у ону која се зове природа:

  1. Отворите конфигурациону датотеку Спхинк цонф.пи у директоријуму вашег пројекта Спхинк.
  2. Потражите линију која дефинише опцију хтмл_тхеме и промените је у природу
  3. Сачувајте конфигурациону датотеку и поново направите документацију да бисте видели промене.

Овако би требало да изгледа почетна страница документације.

Ако не желите да користите уграђене теме, увек можете да користите а тема Сфинге треће стране уместо тога.

Документовање вашег кода помоћу низова докумената

Спхинк генерише вашу Питхон документацију из текста који пишете у РСТ датотекама. Иако је ово довољно у неким случајевима, можда ћете желети да користите низове докумената у свом коду за њега на нивоу модула.

Доцстрингс живе директно у изворним датотекама вашег пројекта. Они вам омогућавају да опишете шта код ради, да дате примере, па чак и да креирате тестове за те примере. Када напишете низове докумената, можете да генеришете документацију од њих користећи Спхинк.