标签: read-the-docs

结构体

以下项目结构:

• index.rst

  MyProject
  =========
  
  Contents:
  
  .. toctree::
  
     group1
  

  Run Code Online (Sandbox Code Playgroud)

• group1.rst

  Group1
  ------
  
  Subgroup1
  =========
  
  Subgroup1 contents
  
  Subgroup2
  =========
  
  Subgroup2 contents
  

  Run Code Online (Sandbox Code Playgroud)

渲染到(点击后Group1- > Subgroup2):

如您所见,它打开Group1页面并链接到Subgroup2部分.

想

我希望在左侧(打开Group1和Subgroup2选择)具有相同的功能,但在右侧我只想看到Subgroup2页面(没有Subgroup1内容的页面).

即有文件group1/subgroup1.rst:

Subgroup2
=========

Subgroup2 contents

呈现给:

如何实现？这是一个深度为2的简单示例,深度为3-4？

我有多个节点的SVG图像文件，每个节点都与URL关联。如果直接在浏览器中打开此文件，则可以单击每个节点，它将打开不同的URL。但是，当我在Sphinx文档中使用此图片时，它不起作用-图片整体呈现，因此我需要打开它，View Image然后才能单击节点。

我正在使用标准的图像指令：

.. image:: myfile.svg

可能我需要使用其他东西吗？

我从包含的ReadtheDocs主题切换到我的项目的bootswatch United主题.我做了pip install mkdocs-bootswatch这个主题,并改变了theme: readthedocs对theme: united我的mkdocs.yml文件.

但是,尽管该项目在阅读文档中成功构建,但文档仍保留标准的readthedocs主题.当我在本地(使用mkdocs serve)运行它时,它与United主题正确显示.

还有另一行代码我应该在某处调整吗？我应该添加一个需求文件？如何让外部主题正确地出现在ReadtheDocs ......或者甚至可以在readthedocs.org上使用外部主题？

注意:我确实问过MkDocs的人,他们说这是一个ReadTheDocs限制,所以如果有什么要做,似乎它将是一个与ReadTheDocs相关的解决方案.否则,我可能不得不切换到GitHub页面或类似的东西.

我一直在制定个人的“操作方法”指南，在我进行的过程中记录并保存我的学习日记。

我现在有一个几乎太长的代码块，当我自己遇到这么长的代码时，试图突出显示块而不突出整个页面总是令人沮丧，或者还不够。

所以，我的问题是，对于rst(reStructuredText).. code-block::的，是否有附加组件或添加copy按钮的方法，用于自动突出显示或自动将文本添加到用户剪贴板？或者这是否是我必须包含在构建中并在代码块中引用它的更多 html 文字类型的代码？如果是这样，那么类似的东西又会是什么样子？

我们开始在 readthedocs 站点（比如http://abc.readthedocs.org）上拥有我们项目的文档。由于各种原因，我们现在使用新域 ( http://abc.io )迁移到我们自己的 Web 服务器。

我们希望优雅地关闭http://abc.readthedocs.org，这样我们的项目文档就不会在整个互联网上被破坏。

我们正在考虑的一种方法是将所有带有前缀 ( http://abc.readthedocs.org ) 的页面“重定向”到 ( http://abc.io )。

但是，我在 readthedocs 站点中没有看到任何提供重定向到全新域的重定向选项。Readthedocs 只允许在同一域下的不同页面内重定向。

关于我如何继续进行的任何指示都会非常有帮助。

我正在为我的项目添加一个Read The Docs页面.现在,我想在我的Read The Docs主页上看到与我的自述文件中相同的内容.我的docs/index.rst文件看起来像:

.. include:: ../README.rst

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

这主要是有效的,除了相对链接.例如,我的README包含:

See `INSTALL.rst`_ for advanced and detailed instructions.

由于Sphinx在docs目录中构建了所有内容,因此期望INSTALL.rst在docs目录中找到它.

由于Github从root渲染文件,因此它希望INSTALL.rst在根目录中找到.

我怎样才能使Github和Read The Docs(Sphinx)正确呈现相对链接而不会有重复文件(或者最好是重复文件)？

我想将 versions.html 包含在侧边栏中，但无法成功。

我尝试在 ** 中为侧边栏添加 versions.html，但这没有效果：

html_sidebars = {
    '**': ['versions.html']
}

还有如何在conf.py.

我看过sphinxcontrib-versioning但它并不完全是我正在寻找的。

我正在使用 Python Sphinx（通过ReadTheDocs）。

我有一个包含几个子模块的存储库，我正在尝试创建一个统一的文档，但仍然单独保留每个模块中的文档资产。

我的文件夹层次结构是：

MyProject
  docs
    index.rst
    module_1_link.rst
      _static
        <more irrelevant assets...>               
  module_1
    docs
      README.rst
      _static
        myimage.png

该index.rst文件看起来是这样的：

.. toctree::
    :caption: Module1
    module_1_link

文件module_1_link.rst仅包含指向模块 1 的 README 文件的链接：

.. include:: ../module1/docs/README.rst

模块 1的README.rst引用了图像：

.. image:: _static/myimage.jpg

当我查看模块 1（在 GitHub 内）的 README 文件时 - myimage.png 显示完美。

但是，当我通过 sphinx 运行文档时，我得到：

 WARNING: image file not readable: _static/myimage.jpg

我找不到从自述文件和 sphinx 呈现的索引文件中引用相同图像的方法，并在两个地方都看到它。

我知道 Sphinx 支持 markdown 或 .md 文件（可选），这对我的补充文档非常有用。我想做的是在 Markdown 文件中使用autoclass或标签。automodule

通常，在一个.rst文件中，如果我这样做

.. autoclass:: my.module.SomeClass
    :members:

它将自动提取所有文档字符串并创建文档。可以在.md文件中使用它吗？目前，当我尝试这样做时，生成的文档仅包含.. autoclass:...预期的内容。

我的conf.py是

.. autoclass:: my.module.SomeClass
    :members:

由于阅读文档的兼容性，我确实考虑了 mkdocs，但它不提供类似 autodoc 的功能。为了实现这一目标，我对任何其他库都非常开放（不必与 RTD 兼容）。

我正在使用阅读文档主题来使用 sphinx 创建 HTML 内容。在主题中，我想编辑“在 Github 上编辑”部分的超链接。我可以使用conf.py文件中的以下变量启用或禁用链接。

html_context = {
    'display_github': True,
    'github_repo': 'xyz',
               }`

这会产生以下链接https://github.com/xyz

1. 但是，我们公司有一个内部 GitLab 存储库，我想将链接更改为https://github.companyname.com/xyz

2. 另外，主题中是否有一个变量来指定分支名称？