Sphinx：记录枚举的正确方法？答案

【问题标题】：Sphinx: Correct way to document an enum?Sphinx：记录枚举的正确方法？
【发布时间】：2013-07-17 03:10:35
【问题描述】：

查看 Sphinx 的 C and C++ domains，它似乎没有原生支持记录枚举（更不用说匿名枚举）了。到目前为止，我使用cpp:type:: 作为枚举类型，然后列出所有可能的值及其描述，但这似乎不是处理它的理想方法，尤其是因为它使引用某些值变得很痛苦（或者我只引用类型，或者在值前面添加一个额外的标记）。

有没有更好的方法来做到这一点？我将如何处理匿名枚举？

【问题讨论】：

标签： c++ python-sphinx restructuredtext

【解决方案1】：

Github 上的一个项目 spdylay 似乎有办法。头文件之一 https://github.com/tatsuhiro-t/spdylay/blob/master/lib/includes/spdylay/spdylay.h 有这样的代码：

/**
 * @enum
 * Error codes used in the Spdylay library.
 */
typedef enum {
  /**
   * Invalid argument passed.
   */
  SPDYLAY_ERR_INVALID_ARGUMENT = -501,
  /**
   * Zlib error.
   */
  SPDYLAY_ERR_ZLIB = -502,
} spdylay_error;

在https://github.com/tatsuhiro-t/spdylay/tree/master/doc 上有一些关于他们如何做到这一点的描述，其中包括使用名为mkapiref.py 的 API 生成器，可在 https://github.com/tatsuhiro-t/spdylay/blob/master/doc/mkapiref.py

它为此示例生成的 RST 是

.. type:: spdylay_error

    Error codes used in the Spdylay library.

    .. macro:: SPDYLAY_ERR_INVALID_ARGUMENT

        (``-501``) 
        Invalid argument passed.
    .. macro:: SPDYLAY_ERR_ZLIB

        (``-502``) 
        Zlib error.

你可以看看它是否对你有用。

【讨论】：

感谢 Alex 的建议——我也需要一个这样的例子！我冒昧地将它为示例生成的 Sphinx 标记编辑到您的答案中。

【解决方案2】：

Sphinx 现在支持 enums

这是一个带有枚举值的示例：

.. enum-class:: partition_affinity_domain

   .. enumerator:: \        
      not_applicable
      numa
      L4_cache
      L3_cache
      L2_cache
      L1_cache
      next_partitionab

【讨论】：

很遗憾，这对我来说为时已晚，但我很高兴为未来的用户解决了这个问题。

【解决方案3】：

嗨，也许你应该考虑使用doxygen 来编写文档，因为它对 c / c++ 有更多的原生支持。如果您想保留文档的 sphinx 输出，您可以从 doxygen 输出为 xml，然后使用 Breathe 它将获取 xml 并为您提供与您习惯相同的 sphinx 输出。

这里是一个从呼吸网站以 doxygen 格式记录枚举的示例。

//! Our toolset
/*! The various tools we can opt to use to crack this particular nut */
enum Tool
{
    kHammer = 0,          //!< What? It does the job
    kNutCrackers,         //!< Boring
    kNinjaThrowingStars   //!< Stealthy
};

希望这会有所帮助。

【讨论】：

我更喜欢 Sphinx 而不是 Doxygen，因为它更容易定制，而且 Breathe 的工作方式与我们编写文档的方式并不完全兼容（此外，查看输出，它们似乎有类似的呈现枚举的问题）。Breathe 和 Doxygen 对我们来说不是可行的选择，抱歉。