如何向TYPO3 Extension添加文档

Question

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

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

我做了所有these pip installs

但是在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

     

发生异常：文件＆＃34; conf.py＆＃34;，第24行，in       import 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直接放入扩展目录，然后再渲染！

   < / LI>

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

Answer 3

您不需要设置Sphinx来编写文档。 文档是纯文本文件，所以没有什么可以阻止你。

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

Answer 4

Do not create an OpenOffice document. You do not need to install sphinx locally! (though no-one can stop you if you want to). You can use the supplied Docker image, which gives you a full working environment for rendering the documentation.

If you still find online resources that recommend to install Sphinx, please let the documentation team know about it by reporting an issue.

The official documentation for writing documentation for extensions has been updated. You can read my answer or you can jump straight to the official documentation in "Writing Documentation":

• How to Start Documentation for your TYPO3 Extension

What documents do you need?

Your extension should have a directory Documentation in it, which should contain reStructuredText (reST) documents (e.g. Index.rst). See Directories and Filenames in "Writing Documentation". Alternatively, you can have a one-file solution (e.g. only Readme.rst), see Additionally supported Filenames and Formats.

For this there are several options:

• There is an example extension manual. How to use this to start your documentation from scratch is already described in the link I gave above.
• Or, start your ReST files from scratch
• Or, use existing extensions for inspiration.
• Or, use the extension builder to create stubs for you (rename the Documentation.tmpl directory to Documentation). This makes sense, of course, if you are using the extension builder to start your extension anyway.

How to edit the .rst files

You can just edit the files in a simple Text Editor or IDE (please use an IDE with reStructuredText and Editorconfig support, use the supplied .editorconfig. In PhpStorm, use the reStructuredText plugin). Obviously, it makes sense to edit the documentation files in your IDE in which you are developing your TYPO3 extension.

• Tip 1: Read the reStructuredText & Sphinx Introduction
• Tip 2: Use the reST & Sphinx Cheat Sheet
• Tip 3: Read Common Pitfalls to avoid errors

Rendering the ReST files

If you want to test how your reST files will look, you should render them locally.

For this you have several options, but the supported method is to use Docker.