TracSphinx 0.2.1

1. 插件安装

下载插件源代码，解压缩归档文件，并从插件文件夹中输入easy_install命令

$ easy_install setup.py install

重新启动Trac项目。作为管理员，我们现在可以激活该插件。

默认情况下，文档源文件夹是项目仓库中的“./docs/source”。但在大多数情况下，我们将在项目“trac.ini”文件的“[sphinx]”部分中覆盖此路径

[sphinx]
source_dir = /<the_doc_source_path>

此源文件夹由项目使用Sphinx的“web”构建器构建sphinx文档。如果无法从Trac生成文档，我们可以使用以下选项指定生成的文档路径

[sphinx]
doc_dir = /<the_doc_dir_path>

我们还可以使用以下选项设置导航栏标题

[sphinx]
navbar_title = My documentation

2. 文档更新

将简单参数放入项目URL中，从项目的源文件夹更新文档到Trac项目的文件夹“./sphinx-docs”。只需输入以下URL进行更新

http://<trac_url>/<project_url>?action=refresh

在某些情况下，文档无法生成，如下列已识别的情况

automodule 无法导入项目的一部分

当我们使用automodule、autoclass..指令时，某些项目无法导入必须的要求或配置。然后Sphinx将不会生成项目文档并返回以下错误

list out of range

像TurboGears应用程序这样的项目可能会受到影响。我们目前正在解决这个问题，并希望很快提出一个解决方案。

3. 文档导航

在Trac中的sphinx文档右侧栏中，我们将找到以下三个功能

• 目录

当前显示页面内容的菜单。

• 相对链接

包含索引和模块项目链接，以及上一页/下一页链接。

• 搜索

简单的sphinx样搜索功能。这里没有javascript，我们在服务器端执行搜索。

4. URL API 概述

插件管理以下 URL 和参数。默认情况下，项目文档的首页将被显示。

• /<project>/sphinx

  默认首页

• /<project>/sphinx?action=view&item=<page_name>

  action=view 显示文档的特定页面 item=page_name 要显示的页面名称 search_words=<some+words> 当前搜索的单词（在页面上突出显示）

• /<project>/sphinx?action=index&item=genindex

  action=index 显示项目文档索引 item=genindex 显示项目文档索引

• /<project>/sphinx?action=modules&item=modindex

  action=index 显示项目模块索引 item=genindex 显示项目模块索引

5. 下次更新

此插件版本实现了 Sphinx 的基本功能。

如果您有更多需求或插件没有以我们期望的方式管理 Sphinx 文档，请随时发送电子邮件或补丁。