有人用Sphinx记录C ++项目吗？ [关闭]

问题描述 投票：44回答：3

Sphinx是Python的新文档工具。看起来很好。我想知道的是：

  • 这对记录C ++项目有多合适？
  • 是否有用于将现有文档（例如doxygen）转换为Sphinx格式的工具？
  • 是否存在使用Sphinx的C ++项目的在线/可下载示例？
  • 从任何使用过狮身人面像的人那里获得的技巧？
python c++ python-sphinx documentation-generation
3个回答
22
投票

如上所述here和here，>>

  • Sphinx本机C ++支持与突出显示/格式化/引用有关，而不与代码内文档提取有关
  • breathe已从chrisdew引用的讨论中发展出来

    • [[编辑在下面插入]：

我在多10k上测试了doxygen + breathe + sphinx工具链C ++库包含10个不同的模块/域。我的屁股行是：

  1. 尚未完全使用
  2. 但继续观看
  3. 而且，最重要的是，如果您当前正在寻找有价值的OSS项目，值得您的时间。

    4. 让我详细说明以下几点：

  1. 我有以下问题：

    • doxygen标记内的乳胶标记（当前不支持，但应该易于实现）
    • 一些解析器错误（几个函数头定义），这似乎导致狮身人面像解析器中的错误，但是如果我测试它们就没有问题直接在sphinx c ++代码块中。不知道修复的难度，但这是一个严重的功能破坏者。
    • 标识符重载有些麻烦。似乎有一些支持用于在不同的类中寻址具有相同名称的函数和/或名称空间和/或doxygen xml输出文件。但是显示或链接到单个类中有10个重载的构造函数中的一个似乎不可行的ATM。在引用/链接的情况下，甚至存在并行（也许是暂时的）呼吸的狮身人面像水平限制能够解决。
    • 当前无法显示所有（或所有受保护/私有）班级成员。这是通过另一种方式引入的并且必须非常简单才能修复。

    • 从更一般的意义上讲，请注意，它的ATM是通向Doxygen的桥梁xml输出。不应以这种方式理解仅在上述限制的情况下，才能准确输出doxygen的功能。而是，它为您提供了[>>

      • 将一个doxygen输出域中的所有内容倾倒到一个巨大的页面上
      • 显示特定的函数，成员，结构，枚举，类型定义或类，但是必须手动指定。 github上有一个叉子可能想要也可能不想解决这个整体概念性问题，但是没有未来的暗示。

  2. 我认为，功能全面的呼吸将填补一个重大空白，开一条很酷的路。因此值得一看，因为潜在收益。

  3. 可悲的是，通过创作者的维护将严重下降在将来。因此，如果您在公司工作并且可以说服你的老板会呼吸很适合他，或者有一些空闲时间，并且寻找一个真正有价值的项目，考虑给它一个分叉！

    4. 作为最后的指针，还要注意狮身人面像的doxylink contrib项目，这可能提供一个中间解决方案：构建一个类似教程的周围环境引用（css样式匹配）旧doxygen文档的结构（我认为您甚至可以将相同的标头注入狮身人面像以及doxygen文档的外观）。这样，您的项目就可以保持对狮身人面像的亲和力，当完全呼吸时，您就准备好了跳上。但是再说一遍：如果适合自己的日程，请考虑表现出喘息的机会。

首先，保留两个目录树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有一个非常酷的插件，叫做automodule，它从Python模块中挑选文档字符串。

Update

从Sphinx 1.0开始，支持C和C ++。 http://sphinx.pocoo.org/

查看XML方法的http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html。

11
投票

首先，保留两个目录树source和build。将source置于版本控制下。不要将build置于版本控制下，请在安装过程中对其进行重建。

4
投票

查看XML方法的http://www.nabble.com/Using-doxygen-and-sphinx-together-td20989904.html。

最新问题
© www.soinside.com 2019 - 2024. All rights reserved.