Использование Sphinx apidoc для создания документации из кода на С++

В прошлом в этой теме было несколько тем, которые утверждают, что Sphinx вообще этого не поддерживает. У меня были сомнения, но либо он был обновлен с тех пор, либо документация для него была довольно скрытой, потому что здесь есть ссылка на веб-сайте, в которой говорится иначе: http://sphinx.pocoo.org/latest/domains.html#array:T:::subscript-operatorC

Во всяком случае, я новичок в Sphinx, но пытаюсь использовать его (в конечном итоге) для автоматизации документации, используя некоторый текст из некоторого исходного кода на С++. До сих пор я нигде не мог найти команду sphinx-apidoc -o........ Создается почти пустой документ. Я, вероятно, не пользуюсь правильными директивами, так как не знаю, как - подтверждающая документация мне не помогла.

Может ли кто-нибудь помочь с основными шагами, необходимыми для его работы? Если невозможно создать автоматическую сгенерированную документацию из С++, для чего нужны С++-домены и как их использовать?

Ответы

Ответ 1

Об автоматической генерации документации на С++:

Прочитав как использовать sphinx, вы должны взглянуть на breathe:

Breathe обеспечивает мост между документацией Sphinx и Doxygen системы.

Это простой способ включить информацию Doxygen в набор документация, созданная Sphinx. Целью является создание автодока как поддержка людей, которым нравится использовать Sphinx, но работать с языками кроме Python. Система основана на выходе xox Doxygens.

Таким образом, вам нужно будет следовать Doxygen стиль комментариев и даже настроить проект doxygen. Но я пробовал это, и он работает очень хорошо после первоначальной настройки. Вот отрывок нашего CMakeLists.txt, который может дать вам представление о том, как сфинкс и doxygen работают вместе:

macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
    add_custom_target(${TARGET_NAME}
    COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
        WORKING_DIRECTORY docs
        DEPENDS doxygen
        COMMENT ${COMMENT_STR}
    )

endmacro(add_sphinx_target)

add_custom_target(doxygen
    COMMAND doxygen docs/doxygen.conf
    COMMENT "Build doxygen xml files used by sphinx/breathe."
)

add_sphinx_target(docs-html
    html
    "Build html documentation"
)

Итак, после первоначальной настройки, по существу, это сводится к:

  • создать документацию doxygen с помощью doxygen path/to/config
  • cd в каталог, где находится конфигурация sphinx.
  • построить документацию sphinx с помощью sphinx-build . path/to/output

В домене С++:

Sphinx - это "немного" больше, чем система для автоматической генерации документации. Я бы предложил вам посмотреть в примерах ( и подумайте, что сам сайт sphinx написан в коде sphinx reST). Особенно нажмите ссылку Show Source на многих сгенерированных сфинксах страницах.

Поэтому, если вы не можете автоматически создавать документацию для проекта, вам нужно сделать это самостоятельно. В основном sphinx является реестром для любого (LaTeX, HTML,...) компилятора. Таким образом, вы можете написать сводный текст, но преимущество в том, что у него есть много команд для документирования исходного кода на разных языках. Каждый язык получает свой собственный домен (префикс или пространство имен) для разделения пространств имен на разных языках. Так, например, я могу документировать функцию python, используя:

.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
    Does something nasty with timers in repetition

(источник)

Я могу сделать то же самое с использованием домена cpp:

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

(источник)

Итак, если вы хотите документировать свой проект С++ без doxygen + дышать, но с sphinx, вам придется писать реструктурированные текстовые файлы самостоятельно. Это также означает, что вы разделяете документацию со своего исходного кода, что может быть нежелательным.

Я надеюсь, что это немного облегчит ситуацию. Для дальнейшего чтения я настоятельно рекомендую вам хорошо прочитать в учебник по sphinx и документация, пока вы не поймете, что она на самом деле делает.