如何向TYPO3 Extension添加文档

Question

是否有一步一步的手册如何将文档添加到TYPO3扩展？ 我在存储库中添加了两个扩展，但我也想添加一些文档。 在TYPO3存储库的早期阶段，这很容易 - 据我记得，必须将OpenOffice文档添加到扩展中...我发现这个“howto”

我正在使用macOS Sierra，我安装了很多东西：Xcode，MacPorts，Sphinx，......

我做了所有这些pip安装

但是在github.com/marble/typo3-docs-typo3-org-resources的文档目录的_make目录中调用make给了我以下内容

错误：

sphinx-build -b html -d build / doctrees -c。 -a -E -w ./_not_versioned/warnings.txt .. build / html运行Sphinx v1.5.1

发生异常：文件“conf.py”，第24行，导入t3SphinxThemeRtd ImportError：没有名为t3SphinxThemeRtd的模块

如果要向开发人员报告问题，则完整的回溯已保存在/tmp/sphinx-err-bGi8t6.log中。 如果是用户错误，请另外报告，以便下次可以提供更好的错误消息。 可以通过https://github.com/sphinx-doc/sphinx/issues在跟踪器中提交错误报告。 谢谢！

所以虽然我用pip命令添加了模块t3SphinxThemeRtd但是找不到它？

是否有一种简单的方法来添加文档？ 我认为这个复杂的程序会阻止许多开发人员在他们的扩展中添加文档！

Answer 1

克里斯蒂安，你完全走在正确的轨道上：是的，提供一些好的文件！ 越来越多的人真的这样做。 所以我敢肯定，2017年将是文件突破的一年。

通常，这是最低要求：将文件./Documentation/Index.rst添加到您的扩展程序并在那里编写您的文档。 使用reStructuredText作为标记。

快速开始：

为了让更好的开始有更多的花里胡哨，这就是你现在应该做的事情：

• 获取一个类似于https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-000/的T3DocumentationStarter项目。

• 阅读首发的首页，了解它的工作原理。

• 例如，这个是为您保留的： https ： //docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-041/

• 直接在Github编辑。 只需做一点更新并保存（=推送），几分钟后你可以重新加载页面，看看服务器为你呈现了什么。 您不必自己安装或渲染任何内容。 服务器会为你做这件事。

• 或者像往常一样与Github合作。

• 要成为该项目的所有者，请将带有Github用户名的邮件发送到docteam到documentation@typo3.org，并要求提供T3DocumentationStarter项目。

• 稍后：将启动项目的./Documentation文件夹复制到您的扩展程序。 写下你的文档。 编辑./Documentation/Settings.cfg中的元数据，您就完成了。

来到文档的阳光一面 - 玩得开心！

PS：现在也在https://docs.typo3.org/Tips/TipOfTheDay/Index.html#how-to-start-documentation-for-your-typo3-extension上

Answer 2

如上所述，您不需要在本地呈现文档，即使它可以使生活更轻松。

1. 使用sphinx：如果你想写第一个文件，看看基本的例子，如https://github.com/georgringer/eventnews或https://github.com/sup7even/mailchimp/tree/master/Documentation

2. 单个文件：但您甚至可以编写更简单的文档。 看看https://github.com/georgringer/page_speed/blob/master/README.rst这是一个单独的文件然后再渲染https://docs.typo3.org/typo3cms/extensions/page_speed/ 。

3. Markdown：如果您对休息感到不舒服，可以将README.md直接放入扩展目录，然后再渲染！

---

可以在此处找到编写文档的完整文档： https ： //docs.typo3.org/typo3cms/CoreApiReference/ExtensionArchitecture/Documentation/Index.html

Answer 3

您无需设置Sphinx来编写文档。 文档是纯文本文件，所以没有什么能阻止你到那里。

不过，当您想要测试文档时，Sphinx很有用。 我向负责文档的Martin Bless报告了您的错误，他将更新指南或尽快与您取得联系。

Answer 4

不要创建OpenOffice文档。 你并不需要在本地安装狮身人面像！ （但如果你愿意，没有人可以阻止你）。 您可以使用提供的Docker镜像，它为您提供了一个完整的工作环境来呈现文档。

编写扩展文档的官方文档已更新：

• 如何启动TYPO3扩展的文档

你需要什么文件？

您的扩展应该有一个目录文档 ，其中应包含文档作为reStructuredText（.rst）文档（例如Index.rst）。 Markdown也受支持。 或者，您可以拥有单文件解决方案（例如，只有Readme.rst）。

• 目录和文件名

要创建扩展文档，有几个选项：

• 有一个示例扩展手册 。 如何使用它从头开始编写文档已在上面给出的链接中描述。
• 或者，从头开始您的ReST文件
• 或者，使用现有的扩展来获取灵感，例如ext：form
• 或者，使用扩展构建器 （将Documentation.tmpl目录重命名为Documentation ）。

如何编辑.rst文件

您可以在简单的文本编辑器或IDE中编辑文件（最好使用支持reStructuredText的IDE，例如对于PhpStorm，使用reStructuredText插件，对于Visual Studio Code，使用LeXtudio reStructuredText插件）。

• 技巧1：阅读reStructuredText和Sphinx简介
• 提示2：使用reST和Sphinx备忘单
• 提示3：阅读常见缺陷以避免错误

呈现ReST文件

如果要测试reST文件的外观，则应在本地呈现它们。

为此您有几个选项 ，但推荐的方法是使用Docker。