标签: python-sphinx

关于我去年关于文档的问题,我现在想要开始并尝试基于Python的Sphinx来整理我一直在研究的PHP CMS的开发人员文档.

我想在我的工作站上本地设置Python,而不是从一开始就在公共可访问的Web服务器上运行它.我有权访问LAMP堆栈上的所有Web托管包,我不愿意购买基于Python的托管.我对Google App Engine非常感兴趣,他们提供的免费配额将为我做一百次,即使没有,他们的定价看起来也很合理.

现在我对Python一无所知 - 让Sphinx工作将是我第一次接触它 - 而且时间很短.据我所知,App Engine提供的平台和python库与标准Python库非常兼容,但不完全相同.

所以我的问题是:

• Sphinx可以在App Engine上运行吗？

• 在App Engine上安装Sphinx就像我在普通的Python安装上安装它一样简单吗？或者,App Engine的环境是否需要调整我在当前Python级别上无法在合理时间内执行的源代码？

• 我应该首先在本地服务器和"普通"Python堆栈上安装Sphinx吗？

• 有没有人知道任何有用的操作方法,教程或其他资源？

这出现在一些地方,但我会用脚注作为例子.假设我有一些引用脚注的ReST文本:

can be rendered in a single batch [#foot-diffuse]_.

呈现时看起来像这样:

引用脚注时,文本后面不应有空格.这就是我想要的样子:

问题是,之间的空间batch和[#foot-diffuse]_不可选的.取出它使得ReST无效,并且脚注根本不会被渲染.有没有办法在ReST中的单词和指令之间插入一个分隔符,而不是在最终输出中将其渲染为空格？

我正在使用Sphinx设置文档.我确切地说,我对这个lib很新.

我的文档可以使用默认主题之一构建.一切正常:)

现在,我想自定义主题.我已经更新了layout.html跟随我的皮肤.在此模板中,我包含globaltoc.html&localtoc.html.toc用toctree()&渲染toc.

我想知道是否有办法更新生成的html或者我是否需要调整我的css到生成的html？

谢谢!

我的文档中有一些图像是作为Sphinx中的一组reST文件创建的.我更喜欢让它们保持很小,我希望用户点击它们以获得更大的图像.较小的图像不是出于文件大小的原因,而是出于演示原因.我没有找到一种语法方法来组合标签image:或figure:与ref:或link:.

.. image:: _static/my_image_small.png

我在同一个文件夹中有一个更大的版本:my_image_large.png.

如果您想出一个解决方案,那么较大的图像应该是一个带有显式链接的文件,还是我创建一个带有附加图像的reST文件:tag？另一种方法是使用reST文件中的图像大小,但后来我仍然不知道如何创建从小图像到大图像的链接.有没有办法绕过Sphinx生成器,只提供我想要的HTML？

Sphinx(http://sphinx-doc.org/index.html)使用重组文本来定义内容.有指令显示来自本地文件系统的图像(使用相对和绝对路径).

我希望能够做的是使用URL声明图像并将其显示为内嵌.我能看到这一点的唯一方法是指定原始HTML,这看起来有点粗糙.有没有替代方案 - 也许是另一个"隐藏"指令或插件来支持这个？

我需要这个的原因是我有很多图像.如果我将它们存储在github上,我将强迫我的用户下载相当大的文件进行同步.我很欣赏我会失去Sphinx警告丢失文件的好处.

html_theme = 'alabaster'使用Sphinx1.3.1 时是否有一种简单的方法来增加换行宽度？

alabaster 现在是默认主题,看起来很棒,除了它非常紧密地包裹线条,我希望能够配置它.

我试图在Sphinx文档中引用一个表格.我为表命名,然后尝试使用numref,但它错误地显示了表的标签("modules_classes")而不是它的编号.

.. _modules_classes:

.. table:: Modules and their corresponding abstract classes

[table content]

Modules and their corresponding abstract classes are presented on table :numref:`modules_classes`.

我也试过这样做,因为我在网上找到了一个例子,但结果是一样的:

.. table:: Modules and their corresponding abstract classes
    :name: modules_classes

我看到它的方式,我不需要导入numfig包,因为它默认包含在Sphinx中.使用该命令:ref:显示表的标题,所以我理解引用是正确的.有人能指出我所做的事情有什么不对吗？

我一直在研究PyQt5的项目(在这里找到:https://github.com/MaVCArt/StyledPyQt5),它使用包结构使导入更合乎逻辑.到目前为止,我已经相对成功地使用Sphinx记录了代码,至少在我介绍包结构之前.(以前,一切都在一个文件夹中)

以下是问题:当我运行sphinx-apidoc时,一切运行正常,没有错误.更重要的是,autodoc很好地接收了我所有的子模块.这是我的一个文件的内容:

styledpyqt package
==================

Subpackages
-----------

.. toctree::
    :maxdepth: 8

    styledpyqt.core

Submodules
----------

styledpyqt.StyleOptions module
------------------------------

.. automodule:: styledpyqt.StyleOptions
    :members:
    :undoc-members:
    :show-inheritance:

styledpyqt.StyleSheet module
----------------------------

.. automodule:: styledpyqt.StyleSheet
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: styledpyqt
    :members:
    :undoc-members:
    :show-inheritance:

如您所知,所有子模块都被拾取.

但是,当我在此运行make html时,这些模块都没有被记录(意味着标题存在,但没有显示任何方法,类或成员).在生成的HTML中,它们只是标题,下面没有任何内容.我知道他们在代码注释中已正确设置,因为代码在现在和包结构的设置之间没有改变,也就是当文档确实有效时.

有没有人有任何想法可能是什么原因？

注意:为了帮助解决这个问题,这里是我的文件夹结构的简短细分:

styledpyqt
+    core
+    +    base
+    +    +    __init__.py ( containing a class definition )
+    +    +    AnimationGroups.py
+    +    +    Animations.py
+    +    __init__.py
+ …

我有一个RST文件,我不希望任何语法高亮.它包含多个文字块和文件顶部的高亮指令,以尝试禁用语法高亮:

.. highlight:: none

::

  Text that happens to contain words like list, None, etc.

::

  Another literal block with words like list, None, etc.

项目中的其他一些RST文件使用语法高亮显示,使用如下指令:

.. highlight:: bash

当我在工作站上使用sphinx构建文档时,sphinx正确地突出显示启用的语法并禁用禁用语法高亮显示的语法.但是,当在readthedocs网站上构建时,在包含RST文件的文字块中会出现不需要的Python语法突出显示.. highlight:: none.突出显示"无"和"列表"之类的单词.

如何在此RST文件中有选择地禁用语法突出显示,同时将语法高亮显示在其他位置？

我正在使用Sphinx来记录python项目。我想在我的文档字符串中使用Markdown格式化它们。即使使用recommonmark扩展名，它也仅涵盖.md手动编写的文件，而不包括文档字符串。

我使用autodoc，napoleon并recommonmark在我的扩展。

如何在我的文档字符串中使Sphinx解析markdown ？