为你的WordPress主题框架编写文档

现在，你已经拥有了一个WordPress主题框架。恭喜你！要相信你之前的辛勤付出，将会得到长远的回报，同时你的开发过程会变得越来越顺利、越来越一体化，也越来越高效。

但是你还需要做的最后一件事，就是为你的框架编写文档。至少，你需要保证你的代码都有合适的说明，这也将有利于编写一些其他的文件，以便你可以进一步跟踪构成框架API（应用程序编程接口）的文件、函数和过滤挂钩。

我将介绍的选项是：

• 说明
• 创建自述文件
• 使用自动化文档工具
• 创建wiki
• 创建一个网站
• 创建教程或录制视频

注意，虽然我会提到一些文档工具，但这并不作为一个正式的推荐，因为我并未在自己的框架中使用过它们，所以你需要自行判断它们是否适用。

编写性质说明

当其他开发人员使用你的代码时（例如，如果你是团队的一分子，或者你会发布你的框架），代码说明就显得特别重要了。即使只是你自己拿来使用，代码说明也是不可替代的。因为一段代码是非常容易就忘了的，特别是你有一年或是更长的时间没有再去编辑它。

想象一下，你使用你的框架创建了一个客户网站。从现在开始的两年内，该网站老在周五下午的5:30出现问题，高质量的代码说明可以让你很快就能修复问题，而没有的话就很困难，区别就是：是回家过周末，还是必须苦读几百行代码，周五晚上也没空出去。

针对高质量的说明，这里有一些很好的技巧：

• 在文件的开头用上一段说明解释文件的功能。例如，在模板文件中就包含有一段说明，关于显示哪些数据和任何循环或文件其他部分的自定义；在插件文件中添加有关其功能说明。例如，下面的说明是告诉用户模板文件的命名、功能，主题是(@package)的一部分，该主题的版本在@since(in place since (@since))。你应该也为插件文件使用类似的系统。

1
2
3
4
5
6
7
8

/**
 * Template Name:    sidebar-products.php
 *
 * The include file used for the sidebar on pages using the single-product.php template. Displays a gallery of product images (omitting the featured image which is displayed in the content).
 *
 * @package wpptl-theme-framework
 * @since version 1.0
 */

• 在样式表、主题模板文件和功能文件中划分代码块时，需要添加说明。
• 非标准内容需要添加说明。
• 花了一段时间解决的内容需要添加说明——使用详细的说明，以便你再回来看时，不必从头到尾再思考一遍。
• 别人会进一步处理的内容需要添加说明——例如，如果你的主题文件包含有待其他开发人员完善的脚本，添加说明解释它们应用于该网站的哪些位置上。
• 添加的说明要求你今后可以很容易地就搜索到——所以不要用缩写，要用别人能理解的术语。
• 每当你注释一些代码时，添加的注释要包含原因。这样，如果你之后忘记了删除过的代码，或者想在将来把它找回时，你就会知道是怎么回事。
• 如果有疑问，也请添加说明！

建立一个自述文件

一个readme.txt文件是说明之后的下一个级别了（the next level up after commenting）。它是一个单独文件，存在于你的主题中，包含有关主题的信息。

此系列教程中的代码包有一个简单的readme.txt文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

Creating your own WordPress theme framework

This theme supports the 6th part of this series for wptutsplus.

The theme includes the following template files:
archive.php
index.php
page.php - for static pages
page-full-width.php
archive.php - for archive pages
header.php
sidebar.php
footer.php
loop.php
loop-single.php
loop-page.php
functions.php

The theme supports featured images, menus and widgets and uses them as follows:

Featured images:
These are displayed in the archive and index templates if they are present, using the medium size.

Menus:
The default menu is in header.php, and uses the Menus admin

Styling
The theme uses Object Oriented CSS (OOCSS). The following clases are for layout and you can use them in your pages and posts.
They are responsive, so will resize on smaller screens (for example the .half class is full width on phones)
.full-width
.three-quarters
.two-thirds
.half
.third
.quarter

Hooks
There are 7 action hooks:
Above the header
Inside the header
Before the content
After the content
In the sidebar
In the footer
After the footer

There are 3 filter hooks:
1 in the header
2 in the footer


Widget Areas
There are six widget areas, all added via the widgets.php file:
- one in the header
- one in the sidebar
- four in the footer

如果你想让你的 readme文件更加人性化的话，可以考虑创建一个readme.html文件，而不是去将其在用户的浏览器中打开。您可以使用CSS来标记你的 readme文件，使得它更容易阅读。

如果你想通过WordPress主题库发布你的主题，向公众开放，你会被要求提供一个readme.txt文件作为一个最小形式的文档。我会在本系列教程的最后一课《发布你的主题框架》中做进一步详细的说明。

使用自动化文档工具

如果你打算继续开发你的框架，而不想花太多时间为每一个新功能编写文档的话，那么一个自动化文档工具也许是一个不错的选择。其中大多数涉及使用特定的标记或语法来使系统能确定在何处生成文档。这样的例子包括：

• PHPDocumentor——特殊PHP
• APIgen——特殊PHP
• Doxygen
• Groc

如果你要使用这些工具，在开始之前值得花一些时间确定哪一种是最适合你的，因为你无法互相传输你的文档。

但是，一旦你掌握了整个系统，并把它建立了起来，那么这些自动化工具就可以为你节省大量的时间，并且可以避免文档间的不一致，另外你要忙着写代码，所以也没有那么多时间来更新你的文档。

创建Wiki或者网站

此选项意味着更大的工作量，只有当你的框架随着时间的推移不断发展，获得了相当数量的用户群的时候，才值得这样做。所有主流的主题框架有自己的网站与文件，要么可以免费访问，要么只提供给会员。

框架的支持网站可能会成为你货币化战略的一部分。例如 hybrid主题框架，它是免费的，但与之配套的网站上的文档和技术支持只提供给付费用户。

另外，如果你将你的框架作为一个收费的产品发布的话，你可以要求用户先登录才能访问该文件，或者你可以选择让你的文档公开，以鼓励更多的人去购买。

如果你的框架是完全免费的，你可以创建一个免费提供文档的网站，Wonderflux框架就是这种情况：

或者，你可能会想去创建一个wiki，优势是能让你的用户贡献自己的文件。大多数情况下，这需要花费更多的时间来建立不止一个网站，但这种工具对使用你框架的社区而言，是十分有用的。您可以为你框架的WordPress网站创建一个wiki。

创建教程或录制视频

教程可以帮助新用户，特别是帮助那些不会写代码的用户了解和掌握你的框架，这比标准文档还要快。视频则更进一步，它是一个易于操作的可视化指南，也可以算作是一种伟大的营销工具。

Genesis框架只给付费用户提供了一系列教程：

我自己的Edupress框架有一些视频教程，目的是帮助不同计算机使用经验背景的用户和没有什么使用经验的WordPress用户：

这些都是显示在公共网站上的，并在用户的仪表板上，所以在使用框架的同时，用户可以很容易地访问到它们。如果你想为你的框架创建文档、教程或视频，你可以在仪表板中包含一个界面，附上你所有文档的详细信息。

但是，创建教程或视频是非常耗时的，工作量巨大：写的不好的教程或制作粗糙的视频将无法很好地反映你的框架，反而可能比简陋的文档造成更多的负面影响。

小结

无论是谁将使用你的主题框架，有一些文件是必不可少的。无论你是为你还是你的团队开发框架，或者是为了更广泛的使用而发布它，你都需要记录文件结构和API（应用程序编程接口）信息。

我在上面讨论的这些选项不仅是从简单的说明到复杂的视频，还包括之间的一切。记住，你要做什么取决于用户的需求，按照这个原则，随着时间的推移，你就会获得越来越多的用户。

• 原文出自：http://code.tutsplus.com/tutorials/writing-documentation-for-your-wordpress-theme-framework--cms-21939
• 由 stonetan@WordPress大学 原创翻译，未经允许，禁止转载和采用本译文。