Repository: trafficserver Updated Branches: refs/heads/master 06f192eb1 -> cbb0d7277
TS-2446: dev guide section on documenting plugins Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/cbb0d727 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/cbb0d727 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/cbb0d727 Branch: refs/heads/master Commit: cbb0d7277a9d672764241c4d62e4c7bcb7987130 Parents: 06f192e Author: Jon Sime <[email protected]> Authored: Thu Feb 11 12:22:47 2016 -0500 Committer: Jon Sime <[email protected]> Committed: Thu Feb 11 12:22:47 2016 -0500 ---------------------------------------------------------------------- doc/developer-guide/documentation/index.en.rst | 1 + .../documentation/plugins.en.rst | 142 +++++++++++++++++++ 2 files changed, 143 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/cbb0d727/doc/developer-guide/documentation/index.en.rst ---------------------------------------------------------------------- diff --git a/doc/developer-guide/documentation/index.en.rst b/doc/developer-guide/documentation/index.en.rst index c4d6fdf..1024da4 100644 --- a/doc/developer-guide/documentation/index.en.rst +++ b/doc/developer-guide/documentation/index.en.rst @@ -31,4 +31,5 @@ Documentation rst-and-sphinx.en ts-markup.en adding-domains.en + plugins.en http://git-wip-us.apache.org/repos/asf/trafficserver/blob/cbb0d727/doc/developer-guide/documentation/plugins.en.rst ---------------------------------------------------------------------- diff --git a/doc/developer-guide/documentation/plugins.en.rst b/doc/developer-guide/documentation/plugins.en.rst new file mode 100644 index 0000000..ea1532d --- /dev/null +++ b/doc/developer-guide/documentation/plugins.en.rst @@ -0,0 +1,142 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +.. include:: ../../common.defs + +.. _developer-doc-plugins: + +Documenting Plugins +******************* + +Plugins can provide tremendously useful functionality for users of |TS|, but it +does them little good if there are no instructions on how to use the plugins +properly. In the interest of encouraging useful documentation on all the +features available to those deploying |TS| in their infrastructure, this +section lays out a series of guidelines and offers a basic template for adding +new entries to the :ref:`admin-plugins` chapter of the :ref:`admin-guide`. + +Structure +========= + +Ideally, every plugin will provide documentation covering the following general +topics (preferably in top-level sections named to match): + +Introduction +------------ + +A brief section in which the plugin's core functionality is explained in a +quickly digestable paragraph or two. For the sake of brevity, this section +should omit discussion of configuration details in favor of providing a more +10,000 foot view of the plugin features. + +Purpose +------- + +Why would someone want to use this particular plugin? What problems does it +solve, or what features not attainable otherwise (through core functionality or +other plugins) does it provide to an administrator or user? While not exactly a +product pitch, this is the section in which the case for using the plugin at +all should be made. + +Dependencies +------------ + +If the plugin has external dependencies, they should be listed in full, with +the exception of items already required by a bare-bones |TS| build. If the +plugin has no unusual or non-standard dependencies, this section may be safely +omitted. + +For example, there is no need to list a C++ compiler as a requirement, but if +the plugin requires OpenCL and a specific brand of GPU expansion card to +perform some wacky image transformations on cached objects - that really should +be disclosed. + +If any of the dependencies are optional, that should be noted as well as the +functionality that may be missing should the dependency not be present. + +Installation +------------ + +Detailed instructions on how to install the plugin if it is not built by +default with |TS| or requires any additional libraries, services, or +applications outside of |TS| to be present. + +If the plugin is marked stable and included by default in |TS| builds, then it +may not be necessary to include any installation steps beyond noting that it is +part of the default |TS|. + +Configuration +------------- + +Detailed instructions on how and where to provide configuration data for the +plugin's features. It is important to use |RST| references for all mentions of +|TS| configuration variables, as well as their containing configuration files. + +If configurations are generated by scripts included with the plugin source +code, those scripts should be mentioned and their usage should be shown. + +Caveats (or Limitations) +------------------------ + +Notes about any peculiarities with the plugin, incompatibilities or strange +behaviors when used in conjunction with other features, or special +considerations for its deployment that might affect an administrator's use of +the plugin or their infrastructure's architecture. + +If the plugin contains known limitations (perhaps it only works with some +protocols, can understand only some media types, or is especially +non-performant under specific configurations) they should be noted. If +possible, workarounds for these limitations should be suggested, or if none are +available that should be noted. + +Examples +-------- + +Every plugin should aim to have at least one, complete example of its usage +beginning with its basic installation, showing a complete (and ideally working) +configuration, as well as sample output from |TS| in which the plugin's effects +may be observed. + +Further Reading +--------------- + +Consolidated list of references to outside materials and documents which may be +relevant to the plugin, such as RFCs and white papers. If the plugin is related +to external projects, or has been the subject of benchmarks or articles, those +may be useful to list as well. + +Additional Sections +=================== + +Not all plugins will fit perfectly within that list of sections. Some may +require additional details, or such extended discussion that it is best to +break the plugin's documentation down a bit further. In general, it is +recommended to place these additional documentation sections in between +*Configuration* and *Caveats* or *Limitations*. + +This ordering permits a quick scanning of the plugin's purpose, basic method of +installation, and initial overview of its configuration before becoming mired +down in dissertation length details of every possible configuration, warning, +and trade-off that may affect deployments. + +In cases where the array of configuration possibilities is extensive, it is +recommended that the initial *Configuration* section describe the most common +configuration scenario(s), while noting that there are many other possibilities +that will be covered in the sections that follow. This, it is hoped, will get +the usual case out of the way quickly for most |TS| administrators while +limiting the paralysis of choice they may face otherwise. +
