标签: python-sphinx

我正在使用Sphinx来记录将部署在不同服务器中的Web服务.该文档中包含用户单击的URL示例,它们应该可以正常工作.我的问题是主机,端口和部署根目录会有所不同,必须为每个部署重新生成文档.

我尝试定义这样的替换:

|base_url|/path
.. |base_url| replace:: http://localhost:8080

但生成的HTML不是我想要的(在生成的链接中不包括"/ path"):

<a href="http://localhost:8080">http://localhost:8080</a>/path

有人知道如何解决这个问题吗？

这是关于Sphinx的先前问题的通用版本.

有没有办法递归自动记录包含其中的类和函数的模块或包？

我认为为每个函数添加autofunctionor automodule指令是愚蠢的; 必须有一种方法来自动化该过程,否则我根本没有看到使用Sphinx的重点.

澄清: 而不是:

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. automethod:: Seg.method_1

        .. automethod:: Seg.method_2

        .. automethod:: Seg.method_3

        .......

        .. automethod:: Seg.method_n

这需要我手动剪切并粘贴所有方法名称并相应地更新文档,我想要一个如下命令:

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. MAGIC COMMAND: Automatically print the docstrings and signatures 
           of all Seg() methods.

我使用sphinx-quickstart创建了一个Sphinx文档.

1. 有没有关于自定义外观的好例子/教程？专门修改标题并添加徽标.

2. 是否有一些可下载Sphinx文档的项目？我想看看他们如何定制他们的外观.

更新:默认设置中支持添加徽标,但没有特别详细记录.看在conf.py了*_logosettings.`

我一直在使用Sphinx和reStructuredText记录软件包.

在我的文档中,有一些很长的代码片段.我希望能够将它们隐藏为默认值,并使用一个"显示/隐藏"按钮来扩展它们(示例).

有没有一种标准的方法可以做到这一点？

有没有办法在sphinx中设置单个单词(或字符)的颜色？我很确定应该有一些标记标记,比如HTML font标记.

我尝试为使用Python 3.x编写的项目创建文档.Sphinx是我想要使​​用的工具,根据官方网站,它的最新版本1.1.2与Python 3.1+兼容.我的操作系统是Archlinux,一个使用Python 3.2+作为默认Python包的Linux发行版.

安装和配置是直接的(easy_install -U Sphinx然后sphinx-quickinstall),我从未被要求在2.x或3.x Python解释器之间进行选择.但是当我要求Sphinx创建我的项目的文档时,我的代码就像我为Python 2.x编写它一样进行分析.

Sphinx是否已准备好使用Python 3.x？我犯了错误吗？

我有以下内容conf.py:

def setup(app):
    app.add_config_value('base_url','http://localhost:2000', True)

如何将其插入我的.rst文件？我写了这个:

:base_url:/my_app/api/application/

但它只打印:base_url:而不是实际的URL.

如何获取要发出的实际配置值？

我最近通过重命名所有模块(除了顶级Cythonized我的一个项目__init__.py)来*.pyx,并通过把ext_modules = [Extension('foo', ['foo.pyx'])]在setup.py.建筑和安装工作正常.但是,当我这样做时cd doc; make html,Sphinx失败了,因为它无法导入任何现在的模块*.pyx.

如果我编辑doc/conf.py并更改sys.path.insert(0, os.path.abspath('..'))为sys.path.insert(0, os.path.abspath('../build/temp.linux-x86_64-2.7')),那么Sphinx可以找到所有模块并可以生成文档,但在这种情况下我会收到类似的错误error while formatting arguments for foo.bar: <built-in function bar> is not a Python function.大概这是因为现在Sphinx只能访问*.so文件,而不是源文件.同样的sys.path修改还允许通过Sphinx(make doctest)运行doctests .

我尝试其他溶液使用扩展*.py,而不是*.pyx(和使用ext_modules = [Extension('foo', ['foo.py'])]中setup.py).在这种情况下,文档正确构建,但我认为doctests现在绕过Cython.

我无法在网上找到有关一起使用Sphinx和Cython的任何信息.我查看了一些使用两者的项目的源代码,但它们似乎没有在*.pyx文件中使用docstrings .我知道Sage确实如此,但是这个项目太复杂了我不能分开.

Sphinx是否支持Cython文件中的文档字符串？如果是这样,我该如何工作呢？

我有一个使用plot-directive的python-3项目,但ReadTheDocs目前不支持这个项目.因此,我想像通常使用PyPi存储库一样生成和上传文档,但是使用该-r选项指定不同的URL.

我尝试了以下,但它失败了:

$ python3 setup.py build_sphinx register upload_docs -r https://readthedocs.org/pypi
running upload_docs
Using PyPI login from /home/user/.pypirc
Using upload directory /home/user/work/wltp.git/docs/_build/html
Submitting documentation to https://readthedocs.org/wltp/pypi
Upload failed (404): OK

我也尝试了以下网址,但没有任何效果:

• https://readthedocs.org/pypi/wltp
• https://readthedocs.org/pypi/wltp/latest
• https://readthedocs.org/wltp/pypi
• https://readthedocs.org/wltp/latest/pypi/

我正在努力实现(原则上)可能吗？

我正在尝试清理我的python代码文档,并决定使用sphinx-doc,因为它看起来不错.我喜欢如何使用以下标签引用其他类和方法:

:class:`mymodule.MyClass` About my class.
:meth:`mymodule.MyClass.myfunction` And my cool function

我试图弄清楚如何在函数中记录参数名称,所以如果我有一个像这样的函数:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something?:`parameter1` And then describe the parameter.

   """

这是最好的做法是什么？

更新:

正确的语法是:

def do_this(parameter1, parameter2):
   """
   I can describe do_this.

   :something parameter1: And then describe the variable
   """