trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject git commit: Documentation update - fixing warnings and errors.
Date Mon, 29 Jul 2013 16:39:37 GMT
Updated Branches:
  refs/heads/master f651f3cf3 -> 80aa69b33


Documentation update - fixing warnings and errors.


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/80aa69b3
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/80aa69b3
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/80aa69b3

Branch: refs/heads/master
Commit: 80aa69b3324ba4f861e2974b31664ff0e561f24b
Parents: f651f3c
Author: Alan M. Carroll <amc@network-geographics.com>
Authored: Mon Jul 29 11:39:21 2013 -0500
Committer: Alan M. Carroll <amc@network-geographics.com>
Committed: Mon Jul 29 11:39:21 2013 -0500

----------------------------------------------------------------------
 doc/admin/getting-started.en.rst | 74 ++++++++++++++---------------------
 doc/ext/traffic-server.py        |  3 ++
 doc/sdk/getting-started.en.rst   | 66 +++++++++++++++----------------
 3 files changed, 64 insertions(+), 79 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80aa69b3/doc/admin/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/getting-started.en.rst b/doc/admin/getting-started.en.rst
index a3e743e..a97c065 100644
--- a/doc/admin/getting-started.en.rst
+++ b/doc/admin/getting-started.en.rst
@@ -3,20 +3,20 @@ Getting Started
 
 .. 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.
+   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.
 
 
 .. toctree::
@@ -81,55 +81,41 @@ if you're building from a git clone, you'll also need
 -  autoconf
 -  automake
 
-We will show-case a build from git:
+We will show-case a build from git::
 
-::
-
-     git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
+   git clone https://git-wip-us.apache.org/repos/asf/trafficserver.git
 
-Next, we ``cd trafficserver`` and run:
-
-::
+Next, we ``cd trafficserver`` and run::
 
-     autoreconf -if
+   autoreconf -if
 
 This will generate a ``configure`` file from ``configure.ac``, so now we
-can run that:
+can run that::
 
-::
-
-     ./configure --prefix=/opt/ats
+   ./configure --prefix=/opt/ats
 
 Note well, that by default Traffic Server uses the user ``nobody``, as
 well as user's primary group as Traffic Server user. If you want to
-change that, you can override it here:
-
-::
+change that, you can override it here::
 
-     ./configure --prefix=/opt/ats --with-user=tserver
+   ./configure --prefix=/opt/ats --with-user=tserver
 
 If dependencies are not in standard paths (``/usr/local`` or ``/usr``),
-you need to pass options to ``configure`` to account for that:
-
-::
+you need to pass options to ``configure`` to account for that::
 
-     ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw
+   ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw
 
 Most ``configure`` path-options accept a format of
-``"INCLUDE_PATH:LIBRARY_PATH"``:
+``"INCLUDE_PATH:LIBRARY_PATH"``::
 
-::
-
-     ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw \
-        --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
+   ./configure --prefix=/opt/ats --with-user=tserver --with-lua=/opt/csw \
+      --with-pcre=/opt/csw/include:/opt/csw/lib/amd64
 
 We can run ``make`` to build the project. We highly recommend to run
-``make check`` to verify the build's general sanity:
-
-::
+``make check`` to verify the build's general sanity::
 
-     make
-     make check
+   make
+   make check
 
 We can finally run ``make install`` to install (you may have to switch
 to root to do this):

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80aa69b3/doc/ext/traffic-server.py
----------------------------------------------------------------------
diff --git a/doc/ext/traffic-server.py b/doc/ext/traffic-server.py
index 9105b1e..a99a0cc 100644
--- a/doc/ext/traffic-server.py
+++ b/doc/ext/traffic-server.py
@@ -20,6 +20,9 @@ class TSConfVar(rst.Directive):
     Argument is the variable as defined in records.config.
 
     Descriptive text should follow, indented.
+    
+    Then the bulk description (if any) undented. This should be considered equivalent to
the Doxygen
+    short and long description.
     """
 
     option_spec = {

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80aa69b3/doc/sdk/getting-started.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started.en.rst b/doc/sdk/getting-started.en.rst
index 81f6e55..aa1535b 100644
--- a/doc/sdk/getting-started.en.rst
+++ b/doc/sdk/getting-started.en.rst
@@ -3,20 +3,20 @@ Getting Started
 
 .. 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.
+   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.
 
 .. toctree::
    :maxdepth: 2
@@ -55,13 +55,12 @@ web-related traffic, such as DNS and HTTP requests and responses.
 Traffic Server itself consists of an event-driven loop that can be
 simplified as follows:
 
-::
+.. code-block:: c
 
-       :::C
-       for (;;) {
-            event = get_next_event();
-            handle_event (event);
-       }
+   for (;;) {
+      event = get_next_event();
+      handle_event (event);
+   }
 
 The Role of Plugins
 ~~~~~~~~~~~~~~~~~~~
@@ -72,19 +71,21 @@ functions that are registered for specific Traffic Server events. When
 Traffic Server needs to process an event, it invokes any and all
 call-back functions you've registered for that event type.
 
-|[Caution]| **Caution**
+.. caution::
 
-Since plugins add object code to Traffic Server, programming errors in a
-plugin can have serious implications. Bugs in your plugin, such as an
-out-of-range pointer, can cause Traffic Server processes to crash and
-may ultimately result in unpredictable behavior.
+   Since plugins add object code to Traffic Server, programming errors in a
+   plugin can have serious implications. Bugs in your plugin, such as an
+   out-of-range pointer, can cause Traffic Server processes to crash and
+   may ultimately result in unpredictable behavior.
 
 **Plugin Process** {#PluginProcess}
 
-.. figure:: /images/sdk/plugin_process.jpg
+.. figure:: /static/images/sdk/plugin_process.jpg
+   :align: center
    :alt: Plugin Process
 
    Plugin Process
+   
 Possible Uses for Plugins
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -125,10 +126,12 @@ Plugins <#possibleTSplugins>`__, illustrates several types of
plugins.
 
 **Possible Traffic Server Plugins** {#possibleTSplugins}
 
-.. figure:: /images/sdk/Uses.jpg
+.. figure:: /static/images/sdk/Uses.jpg
+   :align: center
    :alt: Possible Traffic Server Plugins
 
    Possible Traffic Server Plugins
+   
 You can find basic examples for many plugins in the SDK sample code:
 
 -  ``append-transform.c`` adds text from a specified file to HTTP/text
@@ -161,10 +164,7 @@ The :file:`records.config` file defines the path to each plugin shared
 library, as described in `Specify the Plugin's
 Location <SpecifyingPluginLocation.html>`__.
 
-|[Note]| **Note**
-
-The path for each of these files is *``<root_dir>``*\ ``/config/``,
-where *``<root_dir>``* is where you installed Traffic Server.
+.. note:: The path for each of these files is *<root_dir>*\ ``/config/``, where *<root_dir>*
is where you installed Traffic Server.
 
 Plugin Configuration
 ~~~~~~~~~~~~~~~~~~~~
@@ -243,7 +243,3 @@ The ``TSPluginInit`` function has two arguments:
 
 See `TSPluginInit <InitializationFunctions.html#TSPluginInit>`__ for
 details about ``TSPluginInit``.
-
-.. |[Caution]| image:: /images/docbook/caution.png
-.. |[Note]| image:: /images/docbook/note.png
-


Mime
View raw message