标签: documentation

我有一个包含非常全面的基于XML的文档的程序集,它通过Sandcastle用于生成产品的帮助文件.当程序员明显使用程序集时,我们还使用输出XML文件在Visual Studio中提供正确的Intellisense.

为了做到这一点,我们似乎已经为用户提供了程序集("assembly.dll")和文档("assembly.xml").

是否有可能将文档嵌入到程序集中,因此我们只需提供单个程序集文件,Visual Studio就能提取信息？也许嵌入资源或类似的东西？

我正在使用Sphinx来记录我的python项目.我启用了autodoc扩展,并在我的文档中包含以下内容.

.. autoclass:: ClassName
   :members:

问题是,它只记录了类中的非私有方法.我如何包含私有方法？

我没有找到运算符%的文档,因为它在Python中的字符串上使用.有人知道文档的位置吗？

我正在使用Doxygen和一些嵌入式C源代码.给定一个.c/.h文件对,你是否将Doxygen注释放在函数原型(.h文件)或函数定义(.c文件)上,还是在两个地方都复制它们？

我遇到一个问题,当我在一个地方而不是另一个地方记录时,Doxygen会警告缺少评论; 这是预期的,还是我的Doxygen搞砸了？

我还没有找到一个合理的工作流程来构建包和编写他们的文档.

我希望尽可能多地自动生成流程(和文档).

显而易见的方法是使用package.skeleton创建基本包文件,然后以编程方式覆盖DESCRIPTION文件和Rd文件.这样做的问题在于您丢失了自动生成的字段,确保您记得记录所有正确的参数.

我想知道你如何构建包和编写文档.有没有可用的工具使这个过程更容易？(roxygen看起来像是为这类东西而设计的;有没有一个很好的教程呢？还有其他选择吗？)

我是PHP开发的新手,我想知道社区是否有任何关于使用注释的代码内联文档的指南.我喜欢像Python的PEP 257这样的东西,但我会选择一种流行的文档提取工具使用的格式,甚至是流行产品的文档标准.

我试图在子弹列表中包含reStructuredText的源代码; 像这样:

- List item 1 ::

  code sample...
  code sample...

- List item 2 ::

  code sample...
  code sample...

但是,我收到以下警告: System Message: WARNING/2 Literal block expected; none found.

列表中的空行由单个空格缩进.有任何想法吗？

我是CL的新手,我想学习如何阅读文档字符串并从REPL获取其他帮助信息.像help(symbol)Python中,或symbol?在IPython中,或:t与:i在Haskell的GHCI.

所以,给定一个符号名称,我希望能够知道:

• 它有什么样的价值,如果有的话(一个函数,一个变量,一个都没有)
• 如果它是一个函数或一个宏,那么它的位置参数是什么
• 如果它有文档字符串,请显示它
• 它来自哪个包或文件或何时定义

我找到了(documentation '_symbol_ '_type_),但这不是我需要的.我需要知道的价值符号,势必(类型'function,'variable,'compiler-macro,等)之前,我可以使用documentation.然后它只返回docstring,它可能缺少或不足以使用该符号.

例如,在Lisp中,帮助mapcar不是很有用(CLisp的REPL):

> (documentation 'mapcar 'function)
NIL

我希望能够看到这样的东西:

>>> map?
Type:       builtin_function_or_method
Base Class: <type 'builtin_function_or_method'>
String Form:    <built-in function map>
Namespace:  Python builtin
Docstring:
    map(function, sequence[, sequence, ...]) -> list

    Return a list of the results of applying the function to the items of
    the argument sequence(s).  If more than one …

我正在尝试使用sphinx autodoc扩展,特别是automodule指令自动生成我正在处理的django app的文档.问题是我想创建模块内不同类的内部引用,而不必在项目中的每个类/函数上使用autoclass和autofunction.对于像这样的源文件:

# source_code.py
class A:
    """docs for A
    """
    pass

class B:
    """docs for B with 
    :ref:`internal reference to A <XXXX-some-reference-to-A-XXXX>`
    """
    pass

我希望能够有一个像这样的sphinx文档文件:

.. automodule: source_code

我可以使用什么参考XXXX-some-reference-to-A-XXXX？有没有一种简单的方法来实现这一目标？在此先感谢您的帮助.

如何在本地Haddock文档中嵌入图像？

我看到例如在lens包装只是使用的外部链接的图像,但我想在本地存储的图像.

(这个问题与邮件列表上的(未答复的)问题非常相似).