Подтвердить что ты не робот

Кто-нибудь использовал Sphinx для документирования проекта на С++?

Sphinx - это новый инструмент документации для Python. Это выглядит очень хорошо. Мне интересно:

  • Насколько это подходит для документирования проекта С++?
  • Есть ли инструменты для преобразования существующей документации (например, doxygen) в формат Sphinx?
  • Есть ли онлайн/загружаемые примеры проектов на С++, которые используют Sphinx?
  • Любые советы от тех, кто использовал Sphinx?
4b9b3361

ОТВЕТЫ

Ответ 1

Как уже упоминалось здесь и здесь,

  • Собственная поддержка С++ для Sphinx связана с подсветкой/форматированием/ссылкой, а не с извлечением документации внутри кода.
  • breathe разработал из обсуждения, что chrisdew ссылается на

[Редактировать добавлено ниже]:

Я тестировал инструментарий doxygen + дышать + sphinx на мульти-10k С++ библиотека, состоящая из 10 различных модулей/доменов. Мой нижний строка:

  • еще не полностью используется
  • но продолжайте смотреть
  • и, самое главное, подумайте о том, чтобы посвятить некоторое время себе, если вы в настоящее время ищете ценный проект OSS, который заслуживает ваше время.

Позвольте мне уточнить эти моменты:

  • У меня были проблемы с:

    • Разметка Latex в разметке doxygen (не поддерживается в настоящее время, но должна быть легко реализована)
    • Некоторые ошибки парсера (несколько определений заголовков функций), которые, по-видимому, вызывают ошибки в синтаксическом анализаторе sphinx, но не создавайте проблем, если я их тестирую в блоках кода sphinx С++ напрямую. Не знаю, на чем трудность фиксации, но это серьезный функциональный выключатель.
    • Некоторые проблемы с перегруженными идентификаторами. Кажется, есть какая-то поддержка для адресации функций с одинаковым именем в разных классах и/или пространства имен и/или doxygen xml выходные файлы. Но показ или ссылка на один из 10 перегруженных конструкторов в одном классе кажется недопустимый банкомат. В случае ссылки/связывания существует даже параллель (возможно временное) ограничение уровня сфинкса, которое может дышать, может или не может быть в состоянии обойти.
    • В настоящее время невозможно показать все (или все защищенные/частные) членов класса. Это было каким-то образом введено с другим исправлением и должен быть действительно тривиальным для ремонта.

    • В более общем смысле, имейте в виду, что это ATM - это мост к Doxygen's xml. Это не следует понимать таким образом, чтобы оно точно выводить то, что делает doxygen, только с вышеуказанными ограничениями. Скорее, он предлагает вам ровно, не более, не менее, возможности

      • выгружать все в одном домене doxygen на одну гигантскую страницу
      • показать конкретные функции, члены, структуры, перечисления, typedefs или классы, которые, однако, должны быть указаны вручную. Существует вилка на github которые могут или не могут решить эту общую концептуальную проблему, но никаких намеков на будущее нет.

  • По моему мнению, полностью функциональный дым заполнит большой пробел и открыть довольно прохладную дорогу. Поэтому стоит посмотреть только из-за потенциальный выигрыш.

  • С грустью кажется, что поддержка через создателя сильно опустится в будущем. Поэтому, если вы работаете в компании и можете убедить ваш босс, который дышит, подойдет ему или у вас будет свободное время и ищет действительно ценный проект, подумайте о том, чтобы дать ему вилку!

В качестве конечного указателя также обратите внимание на doxylink contrib project для сфинксов, который может обеспечить промежуточное решение: создать окружающий учебник структура, которая ссылается на старую доксигенную документацию (css-style) (я думаю, вы могли бы даже ввести тот же заголовок в сфинкс, а поверх  доксигенная документация для look'n'feels). Таким образом, ваш проект сродство к сфинксу, и когда дышат полностью там, вы готовы Прыгнуть на. Но опять же: подумайте о том, чтобы показать, как дышит какая-то любовь, если она соответствует вашей повестке дня.

Ответ 2

Сначала сохраните два дерева каталогов source и build. Поместите source под управлением версии. Не ставьте build под контроль версий, перестройте его как часть установки.

Во-вторых, прочитайте http://sphinx.pocoo.org/intro.html#setting-up-the-documentation-sources.

Используйте sphinx-quickstart для создания дерева документации по практике. Играйте с этим в течение нескольких дней, чтобы узнать, как это работает. Затем используйте его снова, чтобы создать реальную вещь в каталогах SVN.

Организуйте свою документацию в хорошо спланированном дереве. Некоторым разделам нужен "index.rst" для этого раздела, некоторые - нет. Это зависит от того, как раздел "автономный".

Наш верхний уровень index.rst выглядит следующим образом.

.. XXX documentation master file, created by sphinx-quickstart on Wed Dec 31 07:27:45 2008.

..  include:: overview.inc

.. _`requirements`:

Requirements
============

.. toctree::
   :maxdepth: 1

   requirements/requirements
   requirements/admin
   requirements/forward
   requirements/volume

.. _`architecture`:

Architecture
============

.. toctree::
   :maxdepth: 1

   architecture/architecture
   architecture/techstack
   architecture/webservice_tech
   architecture/webservice_arch
   architecture/common_features
   architecture/linux_host_architecture

Detailed Designs
================

..  toctree::
    :maxdepth: 3

    design/index


Installation and Operations
===========================

.. toctree::
   :maxdepth: 1

   deployment/installation
   deployment/operations
   deployment/support
   deployment/load_test_results
   deployment/reference
   deployment/licensing

Programming and API's
=====================

..  toctree::
    :maxdepth: 2

    programming/index

**API Reference**. The `API Reference`_ is generated from the source.

.. _`API Reference`: ../../../apidoc/xxx/index.html

..  note::
    The API reference must be built with `Epydoc`_.

    .. _`Epydoc`: http://epydoc.sourceforge.net/

Management
==========

.. toctree::
   :maxdepth: 2
   :glob:

   management/*


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

SVN Revision
============

::

    $Revision: 319 $

Обратите внимание: мы не включаем API, мы просто ссылаемся на него с обычной HTML-ссылкой.

Sphinx имеет очень классное дополнение, называемое автомодулем, которое выбирает docstrings из модулей Python.

Обновление. С Sphinx 1.0 поддерживаются C и С++. http://sphinx.pocoo.org/