Unetway
Установка Sphinx для документирования кода

Установка Sphinx для документирования кода

Sphinx изначально был создан для документации кода на языке программирования Python. Однако его можно использовать и для документирования программ, написанных на разных языках.

Sphinx включает в себя следующие функции:

  1. Автоматическую генерацию документации в таких форматах, как:
    • HTML (в том числе справку Windows HTML)
    • LaTex (для PDF)
    • ePub
    • Texinfo
    • Обычный текст 
  2. Использование абсолютных и относительных ссылок, разметку для кода, цитаты, термины глоссария и т.п.
  3. Иерерхическую струтуру, для определения разделов документа в виде дерева с учетом родительских и дочерних разделов
  4. Обработку и подсветку программного кода
  5. Автоматическое тестирование фрагментов кода и подключение дополнительных модулей.
  6. Установку и подключение тем оформления документации

Для установки Sphinx потребуется совершить следующие действия:

  • Первый шаг - загрузить актуальную версию Python с официального сайта python.org  
  • Второй шаг - после загрузки установщика, дваждый нажать по нему.
  • Третий шаг - следовать рекомендациям в процессе установки

 Примечание. Необходимо убедиться, что выбран пункт «Add Python in PATH», затем нажать на кнопку «Install»

  •  Четвертый шаг - после успешной установки, открыть консоль командой WIN + R (или найти и вызвать из меню ПУСК) и ввести команду:
pip install -U sphinx

Примечание. Если вдруг оказалось, что команда pip не работает, то это означает, что система управления пакетами Python - PIP, при установке Python, не была добавлена в переменные среды Windows.

Для добавления PIP в перемунную среду Windows, нужно произвести следующие действия:

1. Открыть «Панель управления» - «Система и безопасность» - «Система»

2. В левой части выбрать «Дополнительные параметры системы»

3. Затем, перейти на вкладку «Дополнительно» и выбрать «Переменные среды»

4. В открывшемся окне в разделе «Системные переменные» выбрать пункт «Path» и дважды нажать по нему

5. В новом окне выбрать «Создать» и ввести следующее:

C:\Python35\Scripts

Это должно выглядеть примерно так:

Наконец, нажмите ОК во всех открытых окнах.

 Для проверки работы PIP, нужно открыть командную строку и ввести команду - pip. Если настройка выполнена успешно, то будет отображено следующее:

Используете ли вы Sphinx для документирования программ? Если применяете другие инструменты, то какие именно?

Понравился материал? Поделитесь с друзьями!

Автор

Программист с техническим образованием в области IT и опытом программирования на разных языках под различные платформы. Автор многочисленных статей по программированию.

Полезные рекомендации

Комментарии

  1. Сергей месяц назад
    А вы не подскажите, где найти редактор с подсветкой синтаксиса для этой системы? Не возможно большую документацию писать в обычном блокноте без подсветки (я уж не говорю о плюшках любой ide)
    • condor месяц назад
      Сергей, возможно подойдет https://typora.io - редактор в двух режимах: исходного кода с подсветкой и визуального. Можно делать экспорт в различные форматы. Также можете попробовать для редактора Atom поставить пакет "Sphinx-Preview" (есть на официальном сайте Atom, также можно найти через поиск в управлении пакетами редактора), поможет упростить работу с документацией. Пакет разделит область на 2 части: исходный текст документации и визуальную, где наглядно будет отображена сгенерированная документация.
Нажмите здесь, чтобы отменить ответ