如何编写包文档？ [英] How do you write your package documentation?

问题描述

我并没有想出一个合理的工作流来构建软件包并撰写他们的文档。

我想要尽可能多的过程（和文档）要自动生成。

这样做的明显方法似乎是使用 package.skeleton 来创建基本的包文件，然后以编程方式覆盖 DESCRIPTION 文件和 Rd 文件。这样做的麻烦在于，您将丢失自动生成的字段，确保您记住所有正确的参数。

我想知道如何>你关于构建包和编写文档。他们有任何工具可以使流程更容易吗？ （ roxygen 看起来像是为这样的事情而设计的;有没有一个很好的教程，有什么替代方案吗？）

解决方案

我使用roxygen的所有项目。例如，浏览 webvis 包的来源。 Hadley还使用roxygen作为他的文档（例如，见他的 lubridate包）。

据我所知，roxygen没有记录太多超出警戒（看看 roxygen主页）。

Roxygen很好，因为它导致了文字编程，因为您的文档和代码并列。这也使得文档过程更容易一些，因为您一次处理所有内容。我绝对推荐它，并且不会在没有它的情况下开发任何包。

那就是说，它不会使文档自动化，生成工具（例如javadoc）：roxygen解释正确格式化的R注释，但不会以任何方式解释R代码。

关于创建一般包装： package-skeleton 对于初学者来说非常棒。一旦你创建了一些软件包，你可能会在将来轻松创建所有的目录，NAMESPACE等。特别是如果您要遵循其他一些做法，例如包括演示目录，使用roxygen，编写小插件，或将其包含其他语言的源代码。

最后，我在Eclipse（StatET）中管理我的包;许多IDE的项目视图有助于管理包结构，因此您可能还需要使用更高级的编辑器。

I haven't quite figured out a sensible workflow for building packages and writing their documentation.

I want as much of the process (and the documentation) as possible to be automatically generated.

The obvious way to do this seems to be to use package.skeleton to create the basic package files, then programmatically overwrite the DESCRIPTION file and the Rd files. The trouble with this is that you then lose the automatically generated fields that ensure you've remembered to document all the right parameters.

I'd like to know how you go about building packages and writing documentation. Are their any tools available to make the process easier? (roxygen looks like it was designed for this sort of thing; is there a good tutorial for it? and are there any alternatives?)

解决方案

I use roxygen for all my projects. For an example, browse the source for the webvis package. Hadley also uses roxygen for his documentation (e.g. see his lubridate package).

To the best of my knowledge, roxygen isn't documented much beyond the vigette (have a look at the roxygen homepage).

Roxygen is good because it leads to literate programming, in the sense that your documentation and code are side-by-side. This also makes the documentation process a little easier since you're working with everything at once. I definitely recommend it, and won't develop any packages without it at this point.

That said, it doesn't automate the documentation in the sense that some documentation-generation tools do (e.g. javadoc): roxygen interprets R comments that are properly formatted, but it doesn't interpret R code in a any way.

Regarding the creation of the package generally: package-skeleton is great for starters. Once you have created a few packages you may find it easier in the future just to create all the directories, NAMESPACE, etc. by hand. Especially if you are going to follow some of the other practices, such as including a demo directory, using roxygen, writing a vignette, or including source code in other languages.

Lastly, I manage my packages in Eclipse (StatET); many of the IDE's have "project" views that help managing the package structure, so you might also want to use a more advanced editor.

这篇关于如何编写包文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！