如何向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