эпидок

ПРОГРАММА:

ИМЯ

epydoc - создание документации API из строк документации Python

СИНТАКСИС

эпидок [действие] [кредита] имена ...

ОПИСАНИЕ

эпидок генерирует документацию API для модулей и пакетов Python на основе их
строки документации. Облегченный язык разметки под названием эпитекст можно использовать для форматирования
docstrings, а также для добавления информации о конкретных полях, таких как параметры и экземпляр
переменные. Epydoc также понимает строки документации, написанные на ReStructuredText, Javadoc и
простой текст. В настоящее время epydoc поддерживает два основных формата вывода: HTML и LaTeX.

Документация HTML API, созданная эпидок состоит из набора файлов HTML, в том числе:
страницу документации API для каждого класса и модуля; страница исходного кода с синтаксической подсветкой
для каждого модуля; страница индекса идентификатора; справочная страница; и основанная на фреймах таблица
содержание. При необходимости эпидок также будет генерировать индексные страницы для ошибок, определенных
сроки и задачи; страница иерархии классов; и страницу иерархии пакетов.

Документация LaTeX API, созданная эпидок состоит из основного файла LaTeX и файла LaTeX
файл для каждого модуля. Если вы используете --dvi, --пс или --pdf , тогда эпидок вызовет внешние
команды для преобразования вывода LaTeX в запрошенный формат. Обратите внимание, что файлы LaTeX
содержащая документацию по отдельным модулям может быть включена в виде глав или
разделы других документов LaTeX, используя LaTeX \включают команда. Если вы хотите
включить отдельные классы в другие документы LaTeX, а затем использовать - раздельные классы
возможность создать отдельный файл LaTeX для каждого класса.

эпидок также может использоваться для проверки полноты документации API. По умолчанию,
он проверяет, что каждый общедоступный пакет, модуль, класс, метод и функция имеет строку документации
описание. В --тесты Опция может использоваться для указания дополнительных тестов, которые необходимо выполнить.

Воспроизводимый BUILD ПОВЕДЕНИЕ

Использование текущей даты в документации, созданной Epydoc, приводит к документации, которая
является "невоспроизводимым", что означает, что содержимое файлов меняется от сборки к сборке
даже если в исходном дереве этого нет. Чтобы упростить создание воспроизводимых сборок, этот
версия Epydoc поддерживает две функции: --no-include-время сборки вариант и
SOURCE_DATE_EPOCH переменная среды.

Команда --no-include-время сборки вариант можно использовать, если вы заранее знаете, что вам не нужно
создать временные метки в созданной вами документации. В SOURCE_DATE_EPOCH охрана окружающей среды
переменная предназначена для использования системами упаковки, такими как процесс сборки Debian.
Системы упаковки установят SOURCE_DATE_EPOCH к разумной метке времени, которая каким-то образом
связанные с состоянием исходного дерева, и эта временная метка будет использоваться Eypdoc, а не
чем текущая отметка времени. Строит с использованием SOURCE_DATE_EPOCH таким образом будет воспроизводимым.

ДОПОЛНИТЕЛЬНЫЕ ОПЦИИ

Параметры Epydoc разделены на шесть категорий: основные параметры, действия, генерация.
параметры, параметры вывода, параметры графика и параметры возвращаемого значения.

BASIC ДОПОЛНИТЕЛЬНЫЕ ОПЦИИ

имена...
Список объектов, которые необходимо задокументировать. Объекты можно указать с помощью
Имена Python с точками (например, путь к ОС), имена файлов (например, epydoc / epytext.py),
или имена каталогов (например, эпидок /). Имена каталогов определяют пакеты и
расширены, чтобы включить все субмодули и субпакеты. Если вы хотите
исключить определенные субмодули или субпакеты, используйте --исключать вариант
(описано ниже).

--config файл
Файл конфигурации с указанием дополнительных кредитаи / илиимена. Этот вариант
может повторяться.

--к, --тихий, --в, --подробный
Создавать подробный (или подробный) вывод. При многократном использовании этот параметр
последовательно выдает более тихий (или подробный) вывод.

--отлаживать
Показать полные трассировки для внутренних ошибок.

- простой срок
Не пытайтесь использовать цвет или управление курсором при отображении индикатора выполнения,
предупреждения или ошибки.

Действия

--html Напишите вывод HTML. [дефолт]

--латекс Напишите вывод LaTeX.

--dvi Записать выход DVI.

--пс Напишите вывод Postscript.

--pdf Напишите вывод Adobe Acrobat (pdf).

--проверить Выполните проверку комплектности документации.

--соленый огурец Запишите документацию в файл рассола.

ПОКОЛЕНИЕ ДОПОЛНИТЕЛЬНЫЕ ОПЦИИ

--docformat формат
Установите значение по умолчанию для __docformat__ в формат. __docformat__ это модуль
переменная, определяющая язык разметки для строк документации в модуле.
Его значение состоит из названия языка разметки, за которым может следовать
код языка (например, en для английского). Список языков разметки
в настоящее время распознается epydoc, запустите эпидок --Помогите формат документа.

--parse-только
Соберите всю информацию о задокументированных объектах, проанализировав соответствующие
Исходный код Python; в частности, делать использовать самоанализ, чтобы собрать
информация о документируемых объектах. Эту опцию следует использовать, когда
epydoc запускается с ненадежным кодом; или на коде, который не может быть подвергнут интроспекции
из-за отсутствия зависимостей или из-за того, что его импорт вызовет нежелательные
побочные эффекты.

- только для интроспекции
Собирать всю информацию о задокументированных объектах методом самоанализа; в
в частности, делать собирать информацию, анализируя исходный код объекта на Python
код.

--исключать ШАБЛОН
Не документируйте объекты, имя которых соответствует заданному регулярному выражению.
шаблону.

--exclude-интроспектив ШАБЛОН
Не используйте интроспекцию для сбора информации о каком-либо объекте, имя которого
соответствует заданному регулярному выражению.

--exclude-parse ШАБЛОН
Не используйте синтаксический анализ исходного кода Python для сбора информации о каком-либо объекте.
имя которого соответствует заданному регулярному выражению.

--наследование формат
Формат, который следует использовать для отображения унаследованных методов, переменных и
свойства в сгенерированных «сводных» таблицах. Если формат "сгруппировано", тогда
унаследованные объекты собираются в группы в зависимости от того, к какому классу они принадлежат.
унаследовано от. Если формат "перечислен", то унаследованные объекты перечисляются в
краткий список в конце сводной таблицы. Если формат "включен", тогда
унаследованные объекты смешиваются с ненаследуемыми объектами. Формат по умолчанию
для вывода HTML это «сгруппировано».

--шоу-приват, - не частный
Эти параметры определяют, создается ли документация для частных объектов.
По умолчанию сгенерированная документация включает частные объекты, и пользователи могут
выберите, просматривать ли частные объекты или нет, нажав на «показать частные»
и «скрыть частные» ссылки. Но если вы хотите отговорить пользователей напрямую
доступ к частным объектам, тогда вы можете предпочесть не создавать документацию
для частных объектов.

--show-import, - без импорта
Эти параметры управляют включением импорта модуля в сгенерированный
документация. По умолчанию импорт не включен.

--показать исходный код, --без исходного кода
Эти параметры определяют, должен ли epydoc генерировать выделенный синтаксисом
страницы, содержащие исходный код каждого модуля в выводе HTML. По умолчанию,
страницы исходного кода генерируются.

--include-журнал
Создать HTML-страницу epydoc-log.html содержащие все сообщения об ошибках и предупреждения
которые генерируются epydoc, и включают их в сгенерированный вывод.

--no-include-время сборки
Не печатайте время сборки в нижнем колонтитуле страницы. Это полезно, если вы
пытаясь создать воспроизводимые сборки, где каждая сборка соответствует заданному
версия исходного дерева производит точно такие же артефакты.

ВЫВОД ДОПОЛНИТЕЛЬНЫЕ ОПЦИИ

-o директория, --выход директория
Выходной каталог. Если директория не существует, то он будет создан. Если нет
указывается выходной каталог, затем имя действия (например, HTML or PDF). HTML

-c лист, --css лист
Таблица стилей CSS для выходных файлов HTML. Если лист это файл, тогда таблица стилей
копируется из этого файла; иначе, лист считается именем
встроенная таблица стилей. Чтобы получить список встроенных таблиц стилей, запустите эпидок --Помогите
CSS. Если таблица стилей CSS не указана, то таблица стилей по умолчанию
используемый.

-n имя, --имя имя
Название проекта, документация по которому создается.

-u URL, --url URL
URL-адрес домашней страницы проекта.

--navlink HTML
HTML-код для ссылки на домашнюю страницу на панели навигации HTML. Если этот HTML-код
содержит любые гиперссылки (<a href = ...>), то он будет вставлен дословно. Если
он не содержит гиперссылок, и указан URL проекта (с
--url), то к ссылке добавляется гиперссылка на указанный URL.

--help-файл файл
Альтернативный файл справки. файл должен содержать тело HTML-файла -
к нему будут добавлены панели навигации.

- шоу-кадры, - без рамок
Эти параметры определяют, будет ли вывод HMTL включать таблицу на основе кадров
страница содержания. По умолчанию включается оглавление на основе фреймов.

- раздельные классы
В выходных данных LaTeX опишите каждый класс в отдельном разделе
документации, вместо того, чтобы включать их в документацию для своих
модули. Это создает отдельный файл LaTeX для каждого класса, поэтому его также можно
полезно, если вы хотите включить документацию для одного или двух классов как
разделы вашего собственного документа LaTeX.

GRAPH ДОПОЛНИТЕЛЬНЫЕ ОПЦИИ

--граф тип графа
Включить графики типа тип графа в сгенерированном выходе. Графики построены
используя исполняемый файл Graphviz dot. Если этого исполняемого файла нет на пути, то
используют --dotpath указать его местонахождение. Этот вариант можно повторить, чтобы включить
несколько типов графиков на выходе. тип графа должен быть одним из: ВСЕ,
класс, колграф или Umlclasstree.

--dotpath путь
Путь к Графвизу dot исполняемый файл.

--граф-шрифт шрифт
Название шрифта, используемого для создания графиков Graphviz. (например, helvetica или
раз).

--graph-размер-шрифта размер
Размер шрифта, используемого для создания графиков Graphviz, в пунктах.

--pstat файл
Выходной файл pstat, который будет использоваться при создании графиков вызовов.

ВЕРНУТЬ VALUE ДОПОЛНИТЕЛЬНЫЕ ОПЦИИ

--сбой при ошибке
Возвращает ненулевой статус выхода, указывающий на сбой, если есть какие-либо ошибки.
встречается.

- предупреждение о сбое
Возвращает ненулевой статус выхода, указывающий на сбой, если есть какие-либо ошибки или предупреждения
встречаются (не включая предупреждения в строке документации).

--fail-on-docstring-предупреждение
Возвращает ненулевой статус выхода, указывающий на сбой, если есть какие-либо ошибки или предупреждения
встречаются (включая предупреждения в строке документации).

HTML FILES

Документация HTML API, созданная эпидок состоит из следующих файлов:

ОБЪЕКТ ДОКУМЕНТАЦИЯ СТРАНИЦЫ

index.html
Стандартная точка входа в документацию. Как обычно, index.html это копия
файла кадров (кадры.html). Но если - без рамок используется опция, тогда
index.html является копией домашней страницы документации API, которая обычно
страница документации для пакета или модуля верхнего уровня (или страница деревьев, если
нет пакета или модуля верхнего уровня).

модуль-module.html
Документация API для модуля. модуль полное название
модуль, например системы or эпидок.epytext.

класс-class.html
Документация API для класса, исключения или типа. класс это полный
пунктирное имя класса, например epydoc.epytext.Токен or массив.ArrayType.

модуль-pysrc.html
Страница с выделенным синтаксисом, содержащая исходный код Python для модуль. Это
Страница содержит ссылки на страницы документации API.

модуль-дерево.html
Иерархия модулей.

дерево классов.html
Иерархия классов. Эта страница создается только в том случае, если хотя бы один класс
документированы.

ИНДЕКСЫ

идентификатор-index.html
Указатель всех задокументированных идентификаторов. Если индекс идентификатора содержит больше
чем 3,000 записей, то она будет разбита на отдельные страницы для каждого письма,
названный идентификатор-индекс-a.html, идентификатор-индекс-b.html, и т.д.

термин-index.html
Указатель всех явно отмеченных определяющих терминов. Эта страница только
генерируется, если в отформатированной строке документации отмечен хотя бы один термин определения.

ошибка-index.html
Индекс всех явно отмеченных @ошибка поля. Эта страница создается только в том случае, если
хотя бы один @ошибка поле отображается в виде отформатированной строки документации.

todo-index.html
Индекс всех явно отмеченных @делать поля. Эта страница создается только в том случае, если
хотя бы один @делать поле отображается в виде отформатированной строки документации.

изменено-index.html
Индекс всех явно отмеченных @измененный поля. Эта страница только создается
если хотя бы один @измененный поле отображается в виде отформатированной строки документации.

устаревший-index.html
Индекс всех явно отмеченных @устарело поля. Эта страница только
генерируется, если хотя бы один @устарело поле отображается в виде отформатированной строки документации.

с-index.html
Индекс всех явно отмеченных @поскольку поля. Эта страница только создается
если хотя бы один @поскольку поле отображается в виде отформатированной строки документации.

НА ОСНОВЕ РАМ ТАБЛИЦА OF СОДЕРЖАНИЕ

кадры.html
Основной файл кадров. Две рамки в левой части окна содержат
оглавление, а основной фрейм в правой части окна содержит
Страницы документации API.

toc.html
Страница оглавления верхнего уровня. Эта страница отображается в верхнем левом углу.
рамка из кадры.html, а также ссылки на toc-все.html и
ток-модуль-module.html страниц.

toc-все.html
Оглавление всего проекта. Эта страница отображается в
нижний левый кадр кадры.html, и предоставляет ссылки на каждый класс, тип,
исключение, функция и переменная, определенные проектом.

ток-модуль-module.html
Оглавление модуля. Эта страница отображается в нижнем левом углу.
рамка из кадры.html, и предоставляет ссылки на каждый класс, тип, исключение,
функция и переменная, определяемая модулем. модуль это полный пунктирный
имя модуля, например системы or эпидок.epytext.

ДРУГИЕ СТРАНИЦЫ

help.html
Страница помощи по проекту. На этой странице объясняется, как использовать и перемещаться по
веб-страница, созданная epydoc.

перенаправление.html
На этой странице используется javascript для перевода названий с точками в соответствующие им.
URL-адреса. Например, в документации epydoc загрузка страницы
автоматически перенаправит
браузер для .

эпидок.css
Таблица стилей CSS, используемая для отображения всех HTML-страниц.

эпидок.js
Файл javascript, используемый для определения функций javascript, используемых epydoc.

epydoc-log.html
Страница, содержащая журнал всех предупреждений и ошибок, сгенерированных
epydoc вместе с таблицей, в которой перечислены все использованные параметры.

ЛАТЕКС FILES

Документация LaTeX API, созданная эпидок состоит из следующих файлов:

API.pdf
Файл Adobe Acrobat (pdf), содержащий полную документацию по API. Этот
файл создается только в том случае, если вы используете --pdf опцию.

API.tex
Файл LaTeX верхнего уровня. Этот файл импортирует другие файлы LaTeX, чтобы создать
единый унифицированный документ.

API.dvi
Файл dvi, содержащий полную документацию по API. Этот файл только
генерируется, если вы используете --dvi вариант, --пс или --pdf опцию.

API.ps Файл postscript, содержащий полную документацию по API. Этот файл только
генерируется, если вы используете --пс или --pdf опцию.

модуль-module.tex
Документация API для модуля. модуль полное название
модуль, например системы or эпидок.epytext.

класс-класс.tex
Документация API для класса, исключения или типа. класс это полный
пунктирное имя класса, например epydoc.epytext.Токен или array.ArrayType.
Эти файлы документации класса создаются только в том случае, если - раздельные классы
опция используется; в противном случае документация для каждого класса включается в его
файл документации модуля.

ДИАГНОСТИКИ

ЭПИТЕКСТ РАЗМЕТКА ПРЕДУПРЕЖДЕНИЕ СООБЩЕНИЯ
Ошибки Epytext вызваны строками документации Epytext, которые содержат недопустимую разметку. В любое время
обнаружена ошибка эпитекста, соответствующая строка документации рассматривается как открытый текст
строка документации. Epydoc может генерировать следующие ошибки эпитекста:

бассейн ссылке. цель.
Целевой объект, указанный для построения встроенной ссылки (L {...}) не очень хорошо
сформирован. Цели ссылки должны быть действительными идентификаторами Python.

бассейн Связи цель.
Целевой объект, указанный для встроенной конструкции uri (U {...}) неправильно сформирован.
Обычно это происходит, если встроенная разметка вложена в целевой URI.

Поля Чёрный be at топ уровень.
Список полей (@параметри т. д.) содержится в некоторой другой блочной структуре
(например, список или раздел).

Поля Чёрный be окончательный элементов.
Список полей (@параметри т. д.) не находится в конце строки документации.

Заголовки Чёрный происходить at топ уровень.
Заголовок содержится в какой-то другой блочной структуре (например, в списке).

неподходящий доктест блок отступ.
Доктест блокирует удаление после отступа в своей начальной строке приглашения.

неподходящий Заголовок отступ.
Заголовок раздела не выравнивается по левому краю с абзацами в
раздел, который его содержит.

неподходящий пункт отступ.
Абзацы в блоке не выравниваются по левому краю. Эта ошибка часто бывает
генерируется при синтаксическом анализе строк документов с открытым текстом с использованием epytext.

Недействительный побег.
Неизвестная escape-последовательность использовалась со встроенной конструкцией escape
(E {...}).

Списки Чёрный be с отступом.
Строка без отступа сразу после абзаца начинается с маркера списка.
Epydoc не уверен, собирались ли вы начать новый элемент списка или предназначались для
абзац, чтобы включить слово, похожее на пулю. Если вы намеревались
бывший, затем сделайте отступ в списке. Если вы планировали последнее, измените
перенос текста в абзаце или экранирование первого символа слова, которое
похоже на пулю.

неуравновешенный '{'.
Строка документации содержит несбалансированные фигурные скобки. Epytext требует, чтобы все фигурные скобки
должны быть сбалансированы. Чтобы включить одну несбалансированную скобу, используйте escape
последовательности E {lb} (левая фигурная скобка) и E {rb} (правая фигурная скобка).

неуравновешенный '}'.
Строка документации содержит несбалансированные фигурные скобки. Epytext требует, чтобы все фигурные скобки
должны быть сбалансированы. Чтобы включить одну несбалансированную скобу, используйте escape
последовательности E {lb} (левая фигурная скобка) и E {rb} (правая фигурная скобка).

Неизвестный встроенный наценка тег.
Неизвестный тег использовался при построении встроенной разметки ( x{...} ).

Неправильно подчеркивание персонаж для заголовок.
Знак подчеркивания, используемый для заголовка этого раздела, не означает
соответствующий уровень раздела. Знак "=" должен использоваться для подчеркивания
разделы; «-» для подразделов; и "~" для подразделов.

Возможное неправильно отформатированный поле пункт.
Epytext обнаружил строку, которая выглядит как элемент поля, но неправильно
отформатирован. Обычно это происходит, когда конечное двоеточие (":") не включено
в теге поля.

Возможное Заголовок опечатка.
Epytext обнаружил пару строк, которые выглядят как заголовок, но количество
подчеркивание не соответствует количеству символов в заголовке.
Количество символов в этих двух строках должно точно совпадать, чтобы они были
считается заголовком.

ПОЛЕ ПРЕДУПРЕЖДЕНИЯ
Предупреждения о полях вызываются строками документации, содержащими недопустимые поля. Содержание
недопустимое поле обычно игнорируется. Epydoc может создать следующее поле
предупреждения:

@параметр для неизвестный параметр остановить.
Поле @param использовалось для указания типа параметра, который не
включен в сигнатуру функции. Обычно это вызвано опечаткой в
имя параметра.

день сделал ожидать an аргумент.
Тег поля день использовался с аргументом, но не требует его.

день ожидается an аргумент.
Тег поля день использовался без аргумента, но он требует его.

@тип для неизвестный параметр остановить.
Поле @type использовалось для указания типа параметра, который не включен
в сигнатуре функции. Обычно это вызвано опечаткой в
имя параметра.

@тип для неизвестный переменная вар.
Поле @type использовалось для указания типа переменной, но не других
информация о переменной известна. Обычно это вызвано опечаткой в
имя переменной.

Неизвестный поле день день.
Строка документации содержит поле с неизвестным тегом день.

переопределение of поле.
Несколько тегов полей определяют значение поле в той же строке документации, но поле
может принимать только одно значение.

ПРИМЕРЫ

эпидок -n эпидок -u http://epydoc.sf.net эпидок /
Создайте документацию HTML API для пакета epydoc и всех его
подмодули и записать вывод в HTML каталог. В заголовках и
нижние колонтитулы, используйте эпидок в качестве названия проекта и http://epydoc.sf.net как проект
URL.

эпидок --pdf -n эпидок эпидок /
Создайте документацию LaTeX API для пакета epydoc и всех его
подмодули и записать вывод в латекс каталог.

ВЫХОД статус

0 Успешное выполнение программы.

1 Ошибка использования.

2 Epydoc сгенерировал ошибку или предупреждение, и один из вариантов --сбой при ошибке,
- предупреждение о сбое, or --fail-on-docstring-предупреждение было указано.

другими Внутренняя ошибка (исключение Python).

Используйте epydoc в Интернете с помощью сервисов onworks.net