标签: read-the-docs

有没有办法从sphinx中删除"查看页面源"链接生成阅读文档主题页面？

还有一个类似的问题在这里并建议寻找面包屑文件,但我无法找到一个

如果我需要同时支持 30 多个模块的“常规”散文文档和 API 文档，如何最好地构建 Sphinx 文档（用于阅读文档）？

有许多（<10）常规散文文档页面，例如“入门”、“构建代码”、“常见问题解答”、“支持”等。我知道如何处理这些页面。

另一方面，我的项目包含 30 多个模块，这些模块的 API 文档无法从代码（非 Python）中提取，而必须手动编写。每个模块都有 n 个功能，并且每个模块都必须使用相同的结构进行记录。我想要一个.rst每个模块。

因此，我想要的目录结构如下：

docs\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 building.rst\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 faq.rst\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 ...\n\xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 index.rst\n\xe2\x94\x94\xe2\x94\x80\xe2\x94\x80 modules\n    \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 node.rst\n    \xe2\x94\x9c\xe2\x94\x80\xe2\x94\x80 ...\n

在阅读文档侧导航（即目录）中，我希望看到它表示为

+ Building (header 1)\n - chapter 1 (header 2)\n - ...\n+ FAQ\n - question 1\n - ...\n+ Modules\n + node (header 1 from `modules/node.rst`)\n   - node.foo()\n   - node.bar()\n + ...\n

可以/应该通过将另一个index.rst放在modules？

我正在尝试在https://readthedocs.org/上构建文档。

我看不到任何导入matplotlib的文件的文档字符串。

当我查看构建日志时，发现from matplotlib import pyplot as plt失败，并显示以下消息：

/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/checkouts/latest/docs/source/plotting.rst:67: WARNING: autodoc: failed to import function u'dbplot' from module u'artemis.plotting.db_plotting'; the following exception was raised:
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 551, in import_object
    __import__(self.modname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/artemis_ml-1.6-py2.7.egg/artemis/plotting/db_plotting.py", line 3, in <module>
    from artemis.plotting.matplotlib_backend import BarPlot
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/artemis_ml-1.6-py2.7.egg/artemis/plotting/matplotlib_backend.py", line 7, in <module>
    from matplotlib import pyplot as plt
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/matplotlib/pyplot.py", line 115, in <module>
    _backend_mod, new_figure_manager, draw_if_interactive, _show = pylab_setup()
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/matplotlib/backends/__init__.py", line 32, in pylab_setup …

我刚刚将我的文档从 Github 上传到 ReadTheDocs，我发现它在 ReadTheDocs 和我的本地机器上呈现完全不同。我sphinx_rtd_theme在本地机器上使用最新版本。

这是我本地机器上的显示：

这是 ReadTheDocs 上的渲染：

我在 Chrome、Firefox 和 Microsoft Edge 上尝试过，结果相同，所以它似乎不是浏览器问题。

这是我的 conf.py 的副本：

# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these …

我没看到什么？该RTD功能页说：

PDF生成

当您在RTD上构建项目时，我们会自动生成您的项目文档的PDF。我们还会为您上传的每个版本构建它们，因此我们可以托管您最新文档的PDF，以及您最新的稳定版本。

但是，您如何找到PDF版本？一项网络搜索找到了这则2012年博客文章，作者说：

例如，以下是Django-Tastypie的PDF文档的网址：

http://media.readthedocs.org/pdf/django-tastypie/latest/django-tastypie.pdf

Run Code Online (Sandbox Code Playgroud)

您可以将django-tastypie替换为任何Read Docs项目的子弹。

然而，RTD不允许用户通过URL来浏览网站的目录树：http://media.readthedocs.org/pdf/[project slug]/，GET是我403 FORBIDDEN！至少对于项目CookieCutter。

以下 URL 中“blob”后面的单词指向给定存储库的“master”分支：

https://github.com/celery/celery/blob/master/docs/django/first-steps-with-django.rst

根据上述约定，以下 URL 指向什么？

https://github.com/celery/celery/blob/241d2e8ca85a87a2a6d01380d56eb230310868e3/docs/django/first-steps-with-django.rst

我正在阅读celery的最新文档，并想在 Github 上查看它的来源，因此问题来了。请注意，我可以通过转到“master”分支来查看master文档的源代码。

我已经为我想做的大部分事情找到了 sphinx 选项，但是在使用 autodoc 时，我看不到如何在函数签名之间注入空格和水平线。

以下是 autodoc 生成的内容：

get_all_edges(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_edges

get_all_nodes(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_nodes

get_edge_count(network=None, base_url='http://localhost:1234/v1')
   docstring for get_edge_count

这是我想要得到的：

get_all_edges(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_edges

   ------------------------------------------------------------

get_all_nodes(network=None, base_url='http://localhost:1234/v1')
   docstring for get_all_nodes

   ------------------------------------------------------------

get_edge_count(network=None, base_url='http://localhost:1234/v1')
   docstring for get_edge_count

......或接近于此的东西。我对最后一个函数签名是否有尾随分隔符不感兴趣。也许这很简单，但我没有看到。谢谢！

仅供参考，这里是生成我的函数签名的 autodoc 指令：

PyCy3.networks module
---------------------

.. automodule:: PyCy3.networks
    :members:
    :undoc-members:
    :show-inheritance:

如何使用gitlab（或GitHub Actions ）设置CI/CD 工作流程，生成我自己的阅读文档站点并使用gitlab 页面免费托管？

gitlab 或 github 上是否有一个 fork-ready 示例存储库，我可以使用它来自行生成和自行托管我自己的阅读文档站点？

我将Sphinx与“阅读文档”主题一起使用。对于小型内联代码片段，例如在一段文本中提及单个变量，我使用双反引号将代码格式化为文档中所谓的“内联文字”。

1. 这是格式化内联代码片段的正确方法吗？

与正确的代码块不同，内联代码片段不会执行特定于语言的语法突出显示（这很好）。如上面的链接文档所示（请参见下面的屏幕截图），所有此类“内联文字”都被涂成红色。

2. 我怎样才能把这个颜色变成别的颜色？

我只关心 Sphinx 的 HTML 输出。

我有一组 rst 文件，我正在使用 sphinx 在 readthedocs 中构建这些文件。这些文件有多个项目符号列表，但它们没有正确呈现。

文本出现，但没有项目符号或嵌套/缩进。

为了确保它不是我的文件，我从 sphinx_rtd_theme 页面（https://github.com/readthedocs/sphinx_rtd_theme/blob/b07560bf97dad3a4266f6145bd4b662ac708ab00/docs/desmo）直接复制粘贴。

这是 rst 应该呈现的内容（::marker对于 html 文件中的每个列表项）

这就是我使用本地 sphinx / rtd 设置构建相同的 rst 时得到的结果

在我的 conf.py 或其他文件中有什么我需要修复的吗？