Страницы Sphinx vs wiki pages

Question

Если вы просто хотите создать HTML-документацию, в чем преимущества использования Sphinx в качестве документации api против использования MediaWiki?

Answer 1

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

• Легче редактирование файлов во внешнем редакторе
• Версия управления документации с использованием VCS (СВН, ископаемое или GIT)
• Привык к синтаксису уценки

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

Однако, если вы сотрудничаете с нетехническими людьми: mediawiki или fossil-wiki будет легче добавлять их на страницы проекта/обзора и вносить исправления. Точно так же, если ваша документация должна быть синхронизирована с другими документами (кодом или данными), то sphinx-doc в той же системе контроля версий будет иметь мои предпочтения.

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