我想开始使用Sphinx记录我的项目.我告诉Sphinx在使用过程中使用单独的源代码和构建目录sphinx-quickstart.现在我的目录布局如下:
MyProject/
myproject/
__init__.py
mymodule.py
docs/
source/
.static/
.templates/
conf.py
index.rst
build/
Makefile
应该从Sphinx项目的VCS存储库中排除哪些文件(即,因为我使用Git,我应该将什么添加到我的.gitignore文件中)？例如,我是否应该忽略该docs/build/目录,以便不跟踪从Sphinx生成的HTML页面中的更改？
Sphinx文档工具是否提供不同的PDF主题,例如它提供不同的HTML主题？
我用谷歌搜索了这个问题,但找不到答案,这让我相信答案是'不'.不过,我以为我会问这里.
谢谢.
CPython不使用autodoc作为其文档 - 我们使用手写的散文.
对于PEP 3144(ipaddress模块),我想使用sphinx-apidoc生成初始参考文档.这意味着我想要运行两遍操作:
使用sphinx-apidoc为依赖于autodoc的模块发出Sphinx项目
运行sphinx构建器,创建新的reStructuredText源文件,所有autodoc指令替换为内联reStructuredText内容和生成相同输出的标记
第一步很简单,但我不知道如何进行第二步,甚至无法想出以这些方式搜索任何现有项目的好方法.
我正在尝试使用Google代码样式来记录函数,然后我使用带有拿破仑扩展的sphinx来创建文档.该函数是不寻常的,因为它返回两个参数.我认为拿破仑不会这样做.如果是这样,有人可以告诉我他们是如何处理的吗？
def foo(a):
'''one line summary
longer explanation
Args:
a (int): parameter description
Returns:
servers (list): list of servers to use
msg (str): logging message string
'''
pass
也许我收到的消息是,返回多个参数并不是很好的编码风格,但是你可以这样做吗？生成的html将这两行视为一个参数的描述的一部分.如果我在服务器和msg行之间添加换行符,它会有所帮助,但它仍然记录了一个arg.
我想为计算机视觉领域的项目,模块和库集合准备一份文档(主要用c ++编写).为此,我查看了OpenCV文档,您可能知道OpenCV 2.4.x文档基于Sphinx,这是我寻求的确切解决方案.Sphinx的优点是:
但我意识到OpenCV3.0的c ++版本是基于Doxygen记录的,我不知道为什么!因为它没有Sphinx那么有趣.我知道Doxygen可以编译你的代码并提取你的评论,这是一个有用的功能.我也知道有些库(如呼吸)可以作为Doxygen和Sphinx之间的桥梁.
现在我的问题是:
Sphinx支持几种输出格式:
html或dirhtml).pdf或.ps 如何在Microsoft Word文件中获取输出？
使用另一个doc生成器,我设法生成一个单独的html输出文件,然后使用Word应用程序将其转换为Microsoft Word格式.
不幸的是,我不知道生成Word或HTML单页格式的方法.
我正在寻找最好的方法来在reStructured Text中显示带有文本的图像.我发现有几个网站声称它们是如何完成的,但没有一个显示实际的功能示例.有几个显示了看似失败的例子.我实际上正在使用Sphinx(v0.6.6)并希望避免变态它所带来的"原生"CSS.
谢谢.
只是好奇是否有人知道如何在使用latexpdf目标时自定义sphinx输出？我已经看到很多用于html输出的自定义内容,但似乎无法找到自定义pdf输出的任何示例.
具体来说,我有兴趣自定义标题页,页眉,页脚,并可能在内容之前添加几页前面的内容.
有没有人见过这种定制的例子,或者人们在生成pdf时几乎只使用"股票"sphinx输出？谢谢!
这是"ReST Strikethrough" ReST删除的后续行动,但是在Sphinx而不是ReST背景下.我的问题是,在sphinx中是否有一个中心位置放置一个"角色"指令,或者这个指令是否真的必须在sphinx docmentation中的每个第一个文件中重复.
更详细:
使用角色指令很容易为内联文本定义自定义CSS样式(请参阅ReST Strikethrough作为示例):
.. role:: custom
:class: custom
This is an :custom:`inline text`.
转换为html渲染
.. This is an <span class="custom">inline text</span>. ..
此外,可以轻松地将自定义样式表添加到sphinx(请参阅http://www.tinkerer.me/doc/theming.html),在其中添加CSS类选择器以控制"自定义"文本的呈现方式(颜色,删除线,字体大小...)
令我不安的是,在我的实验中,我不得不在每个使用自定义角色的ReST文件中重复角色指令.是否有一个"中心"的地方,我可以为整个网站定义一次？
有没有办法在Sphinx中将类和/或方法标记为已弃用？我只能找到模块的弃用选项.
使用通用的警告会起作用,但不会带有语义含义.