Сфинкс для php кодирует [закрытую] документацию
В дополнение к ответу Andy Irving
это работало на меня (на SQL Server 2005) в аналогичной ситуации, где у меня есть составной ключ, и я должен подкачать поле, которое является частью ограничения на уникальность данных.
ключ: ИЗОДРОМНЫЙ С ПРЕДВАРЕНИЕМ, LNUM rec1: 10, 0 rec2: 10, 1 rec3: 10, 2
и я должен подкачать LNUM так, чтобы результат был
ключ: ИЗОДРОМНЫЙ С ПРЕДВАРЕНИЕМ, LNUM rec1: 10, 1 rec2: 10, 2 rec3: 10, 0
SQL было нужно:
UPDATE DOCDATA
SET LNUM = CASE LNUM
WHEN 0 THEN 1
WHEN 1 THEN 2
WHEN 2 THEN 0
END
WHERE (pID = 10)
AND (LNUM IN (0, 1, 2))
1 ответ
По моему опыту, Sphinx и ReST могут использоваться как общие инструменты документации. В Sphinx нет ничего, что обязывало бы вас использовать его только для проектов на основе Python. Например, в своей работе я использовал его для создания руководства пользователя и справочника по XML-RPC API. В обоих случаях я не использовал sphinx.ext.autodoc или другие специфичные для Python дополнения. Документация была написана «вручную» с использованием в основном общих директив ReST, а не специальных директив, предоставляемых Sphinx. Как бы то ни было, мне пока не нужно создавать специальную директиву ReST для документации, отличной от Python.
Даже если вы работаете с проектом PHP, я думаю, вы найдете Sphinx полезным. Например, большинство директив, предоставляемых разметкой модуля , на самом деле являются довольно общими. Я не понимаю, почему вы не можете или не хотите использовать эти конструкции для документирования материалов на языках, отличных от Python. Точно так же Sphinx упрощает отображение примеров кода на других языках . Существует даже значение конфигурации, позволяющее изменить значение по умолчанию на любой язык, который поддерживает Pygments (включая PHP). Если вы чувствуете себя особенно амбициозным, вы могли бы даже создать расширение Sphinx , чтобы извлечь что-то значимое из вашего PHP-кода.
С учетом всего сказанного, обязательно учитывайте аудиторию вашего проекта документации. Хотя я считаю Sphinx отличным инструментом и рекомендую его для широкого круга проектов по документации, если ваша аудитория ожидает чего-то еще, помните об этом. Например, если вы документировали проект Java, большая часть вашей аудитории может ожидать документы в стиле Javadoc. Если вы отклоняетесь от этого ожидания, убедитесь, что это не просто для удовольствия (т.е. он дает вам лучшую документацию, чем вы получили бы в противном случае), и будьте готовы (вкратце) обосновать то, что вы сделали иначе (например, с помощью Часто задаваемые вопросы, ответ или введение).
Наконец, любая документация лучше, чем ее отсутствие, независимо от инструмента, использованного для ее создания. Используйте любой инструмент, который поможет вам, если это разница между получением чего-либо и отсутствием.
он дает вам лучшую документацию, чем вы могли бы получить в противном случае) и будьте готовы (вкратце) обосновать то, что вы сделали по-другому (например, с помощью ответа на часто задаваемые вопросы или введения).Наконец, любая документация лучше, чем отсутствие документацию, независимо от инструмента, используемого для их создания. Используйте любой инструмент, который поможет вам, если это разница между получением чего-либо и отсутствием.
он дает вам лучшую документацию, чем вы могли бы получить в противном случае) и будьте готовы (вкратце) обосновать то, что вы сделали по-другому (например, с помощью ответа на часто задаваемые вопросы или введения).Наконец, любая документация лучше, чем отсутствие документацию, независимо от инструмента, используемого для их создания. Используйте любой инструмент, который поможет вам, если это разница между получением чего-либо и отсутствием.