t3SphinxThemeRtd 3.6.15

==============================
Docs.TYPO3.Org 的新主题
=========== ==================

：项目：t3SphinxThemeRtd
：团队：TYPO3 文档团队
：作者：Martin Bless <martin.bless@typo3.org>
：许可证：麻省理工学院
：演示：请参阅此演示文档 `t3SphinxThemeRtdDemoDocs
<https://docs.typo3.org/typo3cms/drafts/github/TYPO3-Documentation/t3SphinxThemeRtdDemoDocs/>`__
这是一种“压力测试”，并演示什么是可能的以及
主题如何用过的。这项工作建立在 `https://github.com/snide/sphinx_rtd_theme <https://github.com/snide/sphinx_rtd_theme>`__

的 v0.1.8 之上。



<http://mbless.de/blog/2015/06/16/a-new-theme-for-docs-typo3-org.html>`__。

导航此页面：

.. default-role:: code

.. contents::
:local:
:depth: 3
:backlinks: top


安装
============

使用 PIP 安装主题
---- -----------------------

`PIP <https://pip.pypa.io/en/stable/>`__ 是
`Python <https: //www.python.org/>`__
`PyPi <https://pypi.python.org/pypi>`__的数据包管理器。
't3SphinxThemeRtd' 由 TYPO3 文档团队
提供，可从 PyPi 获得。

使用 ``pip``::

# 从 PyPi 获取并安装最新版本：
pip install --upgrade t3SphinxThemeRtd

# 如果您的系统需要，请运行超级用户：
pip install --upgrade t3SphinxThemeRtd

为了您的兴趣： ``pip`` 用法的一些快速示例::

# find help
pip install --help
pip --help

# 为此在本地安装user only
pip install --upgrade --user t3SphinxThemeRtd

#卸载——不管是PIP还是setup.py安装：
pip uninstall t3SphinxThemeRtd

#搜索PyPi，Python包索引
pip search t3SphinxThemeRtd
pip search sphinx


直接使用'setup.py'安装
---------------------------------

直接从包中安装::

git clone https://github.com/TYPO3-Documentation/t3SphinxThemeRtd.git
cd t3SphinxThemeRtd
(sudo) python setup.py install

# 或者在用户家本地安装：
python setup.py --user install


Usage
=====

在您的文档项目的 ``conf.py`` 文件：

加载模块::

import t3SphinxThemeRtd

选择主题::

html_theme = "t3SphinxThemeRtd"

设置主题路径::

html_theme_path = [t3SphinxThemeRtd.get_html_theme_path()]

或者，如果这是在您的情况下更好，将主题路径添加到
已定义路径的列表中::

html_theme_path = []
# ...
html_theme_path.append(t3SphinxThemeRtd.get_html_theme_path())


TYPO3 用户的特殊信息
------------------------------------------------

1. 禁用或删除任何现有的“TYPO3 代码块”

如果“TYPO3 代码块”是您的“conf.py”文件的一部分，
那么您需要删除或禁用该代码。
您可以通过编写“if 0”而不是“if 1”来轻松做到这一点。

.. figure:: Documentation/Images/disable-typo3-codeblock.png
:alt: 如何在 conf.py 中禁用现有的 TYPO3 代码

块 通过
编写 ``if 0``。

2. 一旦“TYPO3 代码块”被禁用，旧的 `t3sphinx 模块
<https://git.typo3.org/Documentation/RestTools.git/tree/HEAD:/ExtendingSphinxForTYPO3/src/t3sphinx>`__
不再使用。所以你终于摆脱了旧的镇流器
，一些旧的和恼人的错误已经消失了。Sphinx Json
格式的渲染将适用于新主题。

3. 另一方面：由于“t3sphinx 模块”不再被加载
，因此目前没有处理用于配置的 Yaml 文件。这
意味着，至少现在：

- 您必须使用 ``conf.py`` 文件进行配置。
- 您需要将所有必要的设置从可能的 ``GlobalSettings.yml``
和 ``Settings.yml`` 文件移动到 ``conf.py``。

4.也许我们以后会加入Yaml处理。目前这不存在。

5. **快速开始：** 随意复制此
`Typoscript Reference conf.py 示例文件
<Documentation/Examples/TyposcriptReferenceExample-conf.py>`__。
相关部分在最后。


待完成
==========

在博文中查看此“列表”
<http://mbless.de/blog/2015/06/16/a-new-theme-for-docs-typo3-org .html#to-be-done>`__


Changelog
=========

v3.1.0
------
- 发布为 3.1.0
- 使用缩小的 jQuery
- 添加我们的“在 GitHub 上编辑我”按钮

v3.0.0
------

- 第一个公开版本。
我们开始用版本号 3.0.0
对 RTD 主题的这个 TYPO3 分支进行编号，以明显不同于原始的“sphinx_rtd_theme”，即 v0.1.8。

已经完成
------------

在博文中查看这个`列表
<http://mbless.de/blog/2015/06/16/a-new-theme-for-docs-typo3- org.html#already-done>`__


如何构建目录
=================================

阅读这在`原始自述文件<https://github.com/snide/sphinx_rtd_theme>`__中。


贡献或修改主题
====================================

本章摘自`原始README < https://github.com/snide/sphinx_rtd_theme>`__
(然后修改)::

``t3SphinxThemeRtd`` 主要是一个 `Sass <http://sass-lang.com/>`__ 项目，它
需要一些其他的 Sass 库。我们使用 `Bower <http://bower.io/>`__ 来
管理这些依赖项，并使用 Sass 来构建 css。好消息是，有
一组不错的 `Grunt <http://gruntjs.com/>`__ 操作，不仅可以加载
这些依赖项，还可以监视更改、重建 sphinx 演示文档并构建
可分发的版本主题。坏消息是这意味着您需要
设置类似于前端开发人员的环境（而不是
python 开发人员的环境）。这意味着安装 `Node <https://nodejs.org/>`__
和 `Ruby <https://www.ruby-lang.org/>`__。

设置开发环境
--------------------------------

1. 安装`Sphinx <http://sphinx-doc.org/>` __。 安装到`virtual environment <https://virtualenv.pypa.io/en/latest/>`__:: # 也许先激活virtualenv
是个好主意——但不是必需的。然后： pip install sphinx 2. 安装 Sass:: gem install sass 3. 安装 Node、Bower 和 Grunt:: # 安装 node brew install node # 安装 bower 和 grunt npm install -g bower grunt-cli # 现在一切都安装好了，让我们安装主题的依赖项。 cd t3SphinxThemeRtd npm install
























5. 您可能希望将 `Livereload Addons <http://livereload.com/>`__ 添加到您的
Firefox 和 Chrome 浏览器。

6. 现在我们的环境已经设置好了，确保你在你的虚拟环境中，
在终端中进入我们的包并运行 Grunt::

cd t3SphinxThemeRtd
grunt

或者，也许更好，在后台运行 Grunt::

cd t3SphinxThemeRtd
grunt &

这个默认任务将执行以下 **非常酷的事情，让它值得麻烦**。

1. 它将安装和更新任何 Bower 依赖项。
2. 它将运行 sphinx 并构建 demo_docs。
3. 它将监视 Sass 文件的更改并根据更改构建 css。

4. 它会在发现 .rst、.html、.js或 .css 文件发生更改时重建 sphinx demo_docs 。
5. 它将在 localhost:1919 启动本地 Web 服务器。
6. 它将在浏览器中显示 demo_docs。
7. 如果启用 LiveReload，它将自动刷新浏览器 localhost:1919。

还有一个 `grunt copy` 命令，它可以
将 bower 提取的组件中的文件复制到实际的主题目录中。例如，字体以
这种方式移动到正确的位置。

**注意：** 我需要手动运行 ``grunt copy`` 的复制操作。
默认情况下不运行。

自述文件结束。