You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2013/07/11 20:02:26 UTC
[1/2] git commit: docs: use the c sphinx domain to document API
Updated Branches:
refs/heads/master a324f1093 -> abb53535c
docs: use the c sphinx domain to document API
Use the C sphinx domain to document the TS API. This automatically
cross-references, creates links and formats definitions nicely.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/abb53535
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/abb53535
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/abb53535
Branch: refs/heads/master
Commit: abb53535ce2e4debe91ed6f40403ee278f0951b1
Parents: dacfc98
Author: James Peach <jp...@apache.org>
Authored: Thu Jul 11 12:00:11 2013 -0600
Committer: James Peach <jp...@apache.org>
Committed: Thu Jul 11 12:01:39 2013 -0600
----------------------------------------------------------------------
doc/sdk/man/TSAPI.en.rst | 49 +++++++++++++------------
doc/sdk/man/TSDebug.en.rst | 79 ++++++++++++++---------------------------
2 files changed, 52 insertions(+), 76 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/abb53535/doc/sdk/man/TSAPI.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/man/TSAPI.en.rst b/doc/sdk/man/TSAPI.en.rst
index e56e2a4..62a97aa 100644
--- a/doc/sdk/man/TSAPI.en.rst
+++ b/doc/sdk/man/TSAPI.en.rst
@@ -14,14 +14,16 @@
See the License for the specific language governing permissions and
limitations under the License.
+.. default-domain:: c
+
=========
``TSAPI``
=========
Synopsis
========
-| ``#include <ts/ts.h>``
-| ``#include <ts/remap.h>``
+| `#include <ts/ts.h>`
+| `#include <ts/remap.h>`
Description
===========
@@ -71,23 +73,23 @@ Naming conventions
The Traffic Server API adheres to the following naming conventions:
* The TS prefix is used for all function and variable names defined
- in the Traffic Server API. For example, `TS_EVENT_NONE`, `TSMutex`,
- and `TSContCreate`.
-* Enumerated values are always written in all uppercase letters. For example,
- `TS_EVENT_NONE` and `TS_VC_CLOSE_ABORT`.
+ in the Traffic Server API. For example, :data:`TS_EVENT_NONE`, :type:`TSMutex`,
+ and :func:`TSContCreate`.
+* Enumerated values are always written in all uppercase letters.
+ For example, :data:`TS_EVENT_NONE` and :data:`TS_VC_CLOSE_ABORT`.
* Constant values are all uppercase; enumerated values can be seen
- as a subset of constants. For example, `TS_URL_SCHEME_FILE` and
- `TS_MIME_FIELD_ACCEPT`.
-* The names of defined types are mixed-case. For example, `TSHttpSsn`
- and `TSHttpTxn`.
-* Function names are mixed-case. For example, ``TSUrlCreate``\(\)
- and ``TSContDestroy``\(\).
+ as a subset of constants. For example, :data:`TS_URL_SCHEME_FILE` and
+ :data:`TS_MIME_FIELD_ACCEPT`.
+* The names of defined types are mixed-case. For example, :type:`TSHttpSsn`
+ and :func:`TSHttpTxn`. :func:`TSDebug`
+* Function names are mixed-case. For example, :func:`TSUrlCreate`
+ and :func:`TSContDestroy`.
* Function names use the following subject-verb naming style:
TS-<subject>-<verb>, where <subject> goes from general to specific.
This makes it easier to determine what a function does by reading
its name. For example, the function to retrieve the password field
(the specific subject) from a URL (the general subject) is
- `TSUrlPasswordGet`.
+ :func:`TSUrlPasswordGet`.
* Common verbs like Create, Destroy, Get, Set, Copy, Find, Retrieve,
Insert, Remove, and Delete are used only when appropriate.
@@ -98,19 +100,19 @@ When Traffic Server is first started, it consults the plugin.config
file to determine the names of all shared plugin libraries that
need to be loaded. The plugin.config file also defines arguments
that are to be passed to each plugin's initialization function,
-``TSPluginInit``\(\). The records.config file defines the path to
+:func:`TSPluginInit`. The :file:`records.config` file defines the path to
each plugin shared library.
-The sample plugin.config file below contains a comment line, a blank
+The sample :file:`plugin.config` file below contains a comment line, a blank
line, and two plugin configurations::
# This is a comment line.
my-plugin.so www.junk.com www.trash.com www.garbage.com
some-plugin.so arg1 arg2 $proxy.config.http.cache.on
-Each plugin configuration in the plugin.config file resembles a
-UNIX or DOS shell command; each line in plugin.config cannot exceed
-1023 characters.
+Each plugin configuration in the :file:`plugin.config` file resembles
+a UNIX or DOS shell command; each line in :file:`plugin.config`
+cannot exceed 1023 characters.
The first plugin configuration is for a plugin named my-plugin.so.
It contains three arguments that are to be passed to that plugin's
@@ -121,19 +123,20 @@ Traffic Server will look up the specified configuration variable
and substitute its value.
Plugins are loaded and initialized by Traffic Server in the order
-they appear in the plugin.config file.
+they appear in the :file:`plugin.config` file.
Plugin initialization
=====================
Each plugin must define an initialization function named
-``TSPluginInit``\(\) that Traffic Server invokes when the plugin
-is loaded. ``TSPluginInit``\(\) is commonly used to read configuration
-information and register hooks for event notification.
+:func:`TSPluginInit` that Traffic Server invokes when the
+plugin is loaded. :func:`TSPluginInit` is commonly used to
+read configuration information and register hooks for event
+notification.
Files
=====
-${CONFIG_DIR}/plugin.config, ${CONFIG_DIR}/records.config
+:file:`$CONFIG_DIR/plugin.config`, :file:`$CONFIG_DIR/records.config`
See also
========
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/abb53535/doc/sdk/man/TSDebug.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/man/TSDebug.en.rst b/doc/sdk/man/TSDebug.en.rst
index d202a75..a2ec097 100644
--- a/doc/sdk/man/TSDebug.en.rst
+++ b/doc/sdk/man/TSDebug.en.rst
@@ -14,89 +14,61 @@
See the License for the specific language governing permissions and
limitations under the License.
+.. default-domain:: c
+
==========
-``TSDebug``
+`TSDebug`
==========
-.Nm TSDebug,
-.Nm TSError,
-.Nm TSIsDebugTagSet,
-.Nm TSDebugSpecific,
-.Nm TSHttpTxnDebugSet,
-.Nm TSHttpSsnDebugSet,
-.Nm TSHttpTxnDebugGet,
-.Nm TSHttpSsnDebugGet,
-.Nm TSAssert,
-.Nm TSReleaseAssert
-
Library
=======
Apache Traffic Server plugin API
Synopsis
========
-| ``#include <ts/ts.h>``
-|
-| void
-| ``TSDebug``\(`const char * tag`, `const char * format`, `...`\)
-|
-| void
-| ``TSError``\(`const char * tag`, `const char * format`, `...`\)
-|
-| int
-| ``TSIsDebugTagSet``\(`const char * tag`\)
-|
-| void
-| ``TSDebugSpecific``\(`int debug_flag`, `const char * tag`, `const char * format`, `...`\)
-|
-| void
-| ``TSHttpTxnDebugSet``\(`TSHttpTxn txnp`, `int on`\)
-|
-| void
-| ``TSHttpSsnDebugSet``\(`TSHttpSsn ssn`, `int on`\)
-|
-| int
-| ``TSHttpTxnDebugGet``\(`TSHttpTxn txnp`\)
-|
-| int
-| ``TSHttpSsnDebugGet``\(`TSHttpSsn ssn`\)
-|
-| void
-| ``TSAssert``\(`expression`\)
-|
-| void
-| ``TSReleaseAssert``\(`expression`\)
+`#include <ts/ts.h>`
+
+.. function:: void TSDebug(const char * tag, const char * format, ...)
+.. function:: void TSError(const char * tag, const char * format, ...)
+.. function:: int TSIsDebugTagSet(const char * tag)
+.. function:: void TSDebugSpecific(int debug_flag, const char * tag, const char * format, ...)
+.. function:: void TSHttpTxnDebugSet(TSHttpTxn txnp, int on)
+.. function:: void TSHttpSsnDebugSet(TSHttpSsn ssn, int on)
+.. function:: int TSHttpTxnDebugGet(TSHttpTxn txnp)
+.. function:: int TSHttpSsnDebugGet(TSHttpSsn ssn)
+.. function:: void TSAssert(expression)
+.. function:: void TSReleaseAssert(expression)
Description
===========
-``TSError``\(\) is similar to ``printf``\(\) except that instead
+:func:`TSError` is similar to :func:`printf` except that instead
of writing the output to the C standard output, it writes output
to the Traffic Server error log.
-``TSDebug``\(\) is the same as ``TSError``\(\) except that it only
+:func:`TSDebug` is the same as :func:`TSError` except that it only
logs the debug message if the given debug tag is enabled. It writes
output to the Traffic Server debug log.
-``TSIsDebugSet``\(\) returns non-zero if the given debug tag is
+:func:`TSIsDebugTagSet` returns non-zero if the given debug tag is
enabled.
-In debug mode, ``TSAssert``\(\) Traffic Server to prints the file
+In debug mode, :func:`TSAssert` Traffic Server to prints the file
name, line number and expression, and then aborts. In release mode,
the expression is not removed but the effects of printing an error
-message and aborting are. ``TSReleaseAssert``\(\) prints an error
+message and aborting are. :func:`TSReleaseAssert` prints an error
message and aborts in both release and debug mode.
-``TSDebugSpecific``\(\) emits a debug line even if the debug tag
+:func:`TSDebugSpecific` emits a debug line even if the debug tag
is turned off, as long as debug flag is enabled. This can be used
-in conjuction with ``TSHttpTxnDebugSet``\(\), ``TSHttpSsnDebugSet``\(\),
-``TSHttpTxnDebugGet``\(\) and ``TSHttpSsnDebugGet``\(\) to enable
+in conjuction with :func:`TSHttpTxnDebugSet`, :func:`TSHttpSsnDebugSet`,
+:func:`TSHttpTxnDebugGet` and :func:`TSHttpSsnDebugGet` to enable
debugging on specific session and transaction objects.
Examples
========
-This example uses ``TSDebugSpecific``\(\) to log a message when a specific
+This example uses :func:`TSDebugSpecific` to log a message when a specific
debugging flag is enabled::
#include <ts/ts.h>
@@ -108,4 +80,5 @@ debugging flag is enabled::
SEE ALSO
========
-:manpage:`TSAPI(3ts)`
+:manpage:`TSAPI(3ts)`,
+:manpage:`printf(3)`
[2/2] git commit: docs: add sphinx.ext.intersphinx extension
Posted by jp...@apache.org.
docs: add sphinx.ext.intersphinx extension
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/dacfc98c
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/dacfc98c
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/dacfc98c
Branch: refs/heads/master
Commit: dacfc98cda69a2fb49226d30cb58ca85e3802cce
Parents: a324f10
Author: James Peach <jp...@apache.org>
Authored: Thu Jul 11 11:55:21 2013 -0600
Committer: James Peach <jp...@apache.org>
Committed: Thu Jul 11 12:01:39 2013 -0600
----------------------------------------------------------------------
doc/conf.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/dacfc98c/doc/conf.py
----------------------------------------------------------------------
diff --git a/doc/conf.py b/doc/conf.py
index eb72372..ba55897 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -25,7 +25,7 @@ import sys, os
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']