Python sphinx 强氧+；斯芬克斯+；呼吸+；呼气

目前，我正在编写项目文档。当我在conf.py中包含源文件和头文件时，HTML成功生成。但当我只想使用源文件来记录HTML文件时，它有一些错误。如:

我的conf.py内容如下：

# Setup the exhale extension
exhale_args = {
    # These arguments are required
    "containmentFolder":     "./api",
    "rootFileName":          "library_root.rst",
    "rootFileTitle":         "Library API",
    "doxygenStripFromPath":  "..",
    # Suggested optional arguments
    "createTreeView":        True,
    # TIP: if using the sphinx-bootstrap-theme, you need
    # "treeViewIsBootstrap": True,
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin": textwrap.dedent('''
        EXTRACT_ALL = YES
        SOURCE_BROWSER = YES
        EXTRACT_STATIC = YES
        OPTIMIZE_OUTPUT_FOR_C  = YES
        HIDE_SCOPE_NAMES = YES
        QUIET = YES
        INPUT = ../include ../src
        FILE_PATTERNS = *.c *.h
        EXAMPLE_RECURSIVE = YES
        GENERATE_TREEVIEW = YES
    ''')
}

具有成功结果的源文件和头文件

[源文件]

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

/**
 * \brief Fills the data buffer
 * \param[in] data data buffer for content preparation
 * \return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

[头文件]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

// char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif
/* @cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT */
char* at_test_action(void* data);
/* @endcond */

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

结果失败的源文件和头文件

[源文件]

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

/**
 * \brief Fills the data buffer
 * \param[in] data data buffer for content preparation
 * \return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

[头文件]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

// char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif
/* @cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT */
char* at_test_action(void* data);
/* @endcond */

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

我可以使用不带头文件的Doxygen来生成我想要的结果。 多谢各位

2020.01.31更新（UTC时间：02:51）

由于重复的文档，我想将下面的注释添加到头文件中。

@cond将此部分包含在氧气输出中

/*@endcond*/

[头文件]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

// char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif
/* @cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT */
char* at_test_action(void* data);
/* @endcond */

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

[源文件]

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

/**
 * \brief Fills the data buffer
 * \param[in] data data buffer for content preparation
 * \return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

如果不高于@cond，则氧气结果如下。事实上，在Doxygen中表示对我有好处。

但当更改为Sphinx表示时，用户将在侧栏中看到两个相同的函数和列表，而没有任何详细信息来区分它们：

---

我是这些工具的新手，如果有愚蠢的问题或信息不足，请让我知道。非常感谢。

一个问题是在doxygen中不正确地使用

@param

语句。语法是

\param'['dir']'{parameter description}

---

在您的示例中，参数名称将是

Data

，而参数实际上是

Data

。据我猜测，您的预期用途是

@param[in]数据缓冲区

为什么要注释掉原型？您使用的是哪种型号的强氧剂？问题可能来自Sphinx等的后处理。这可能要求当包含文件存在时，它应该包含原型。为什么要注释掉原型？因为我想处理重复文档，所以我将在DOXYGEN输出中添加INCLUDE\u THIS\u SECTION\u，如上面的更新。您使用的是哪种型号的强氧剂？1.8.16非常感谢。更新的问题中写道：“但当更改为Sphinx表示时，用户将在侧栏中看到两个相同的函数和列表，而没有任何详细信息来区分它”，因此，对我来说，Sphinx实际上无法正确输出数据。是的，但我认为当我排除头文件时，源文件注释应正确输出。但是我不知道为什么我不能得到好的结果。