update #72

docs/source/deployment.rst

@@ -9,7 +9,7 @@ The next step is to move it into production mode, i.e. the final deployment on a
     Running with the built-in development server is not recommended for production as it offers sub-optimal performance,
     scalability, and security.
 
-It is assumed you used the ``clamnewproject`` tool, as explained in `getting started <#sec:gettingstarted>`_, to get
+It is assumed you used the ``clamnewproject`` tool, as explained in `getting started <#gettingstarted>`_, to get
 started with your project. It generated various example configurations for production environments you can use.
 
 Amongst the generated scripts is a WSGI script (recognisable by the ``wsgi`` extension). WSGI is a calling convention
@@ -55,7 +55,7 @@ For nginx, uWSGI support should already be compiled in. Configurations are commo
    open to the public, and only the HTTP/HTTPS port is.
 
 
-.. _sec:modwsgi:
+.. _modwsgi:
 
 Alternative deployment on Apache 2 with mod_wsgi
 --------------------------------------------------
@@ -139,4 +139,4 @@ lighttpd), should work too.
 
 .. seealso::
 
-    For configuration authentication, see `the authentication section <#sec:auth>`_ of the documentation.
+    For configuration authentication, see `the authentication section <#auth>`_ of the documentation.

docs/source/gettingstarted.rst

@@ -1,4 +1,4 @@
-.. _sec:gettingstarted:
+.. _gettingstarted:
 
 Getting Started
 =================
@@ -30,7 +30,7 @@ webservice.
 -  ``myfirstproject/myfirstproject.$HOSTNAME.yml`` - Host-specific
    external configution file which is automatically included from the
    service configuration file if ran on the specified host. This will be
-   addressed `later <#sec:externalconf>`_.
+   addressed `later <#externalconf>`_.
 
 -  ``myfirstproject/myfirstproject_wrapper.py`` - System Wrapper Script
    in Python (this is recommended over the bash version, suited for more
@@ -63,7 +63,7 @@ Moreover, some scripts and sample configurations are generated:
    specific host), used for production environments
 
 -  ``*.conf`` - Sample configuration files for production environments
-   using a Apache 2 or Nginx webserver. Consult the section on `deployment <#sec:deployment>`_ for details.
+   using a Apache 2 or Nginx webserver. Consult the section on `deployment <#deployment>`_ for details.
 
 These template files need to be edited for your particular application.
 They are heavily commented to guide you. The ``INSTRUCTIONS.rst`` file will
@@ -76,19 +76,19 @@ to direct your browser once the webservice is running.
 You can choose not to make use of one of the generated system wrapper
 scripts and instead either write one from scratch in another language of
 your choice, or directly let CLAM invoke your application. Moreover, a
-wrapper is intended for the project paradigm, the `action paradigm <#sec:actions>`_ does
+wrapper is intended for the project paradigm, the `action paradigm <#actions>`_ does
 not make use of it.
 
 Starting Your webservice
 ---------------------------
 
 You can start your webservice in development mode with the included ``startserver_development.sh`` script, but not
-before you first read how to construct your webservice. Read the the `service configuration <#sec:serviceconfig>`_ documentation, and afterwards the `wrapper script <#sec:wrapperscript>`_ documentation.
+before you first read how to construct your webservice. Read the the `service configuration <#serviceconfig>`_ documentation, and afterwards the `wrapper script <#wrapperscript>`_ documentation.
 
 The start script simply installs your webservice and runs ``clamservice`` to run it, passing the module name of your
 webservice configuration. Make sure you first activated your Python virtual environment (if used) when calling the start script.
 
-For production environments, read the documentation on `deployment <#sec:deployment>`_.
+For production environments, read the documentation on `deployment <#deployment>`_.
 
 Overriding host, port and urlprefix (advanced)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/index.rst

@@ -139,23 +139,23 @@ CLAM presents two different paradigms for wrapping your script or
 application. The second is a new addition since CLAM 0.9.11 . You may
 use either or both at the same time.
 
-#. **Project Paradigm** – Users create projects, upload files with
+#. `Project Paradigm <#project>`_ – Users create projects, upload files with
    optional parameters to those projects, and subsequently start the
    project, optionally passing global parameters to the system. The
    system may run for a long time and may do batch-processing on
    multiple input files.
 
-#. `Action Paradigm <#sec:actions>`_ – This is a more limited, and simple
+#. `Action Paradigm <#actions>`_ – This is a more limited, and simple
    remote-procedure call mechanism. Users interact in real-time with the
    service on specific URLs, passing parameters. Unlike the project
    paradigm, this is not suitable for complex operations on big-data.
 
 A CLAM webservice needs the following three components from the service
 developer:
 
-#. A `service configuration <#sec:serviceconfiguration>`_
+#. A `service configuration <#serviceconfiguration>`_
 
-#. A `wrapper script <#sec:wrapperscript>`_ for your command line application;
+#. A `wrapper script <#wrapperscript>`_ for your command line application;
 
 #. A command line application (your NLP tool)
 

docs/source/installation.rst

@@ -16,8 +16,8 @@ CLAM is written for Python 3, which we will use in this documentation. It also s
 Python 2.7.
 
 We recommend you first create a Python Virtual Environment.
-To create a virtual environment, which we name *clamenv* here, but you
-can choose any name you want, issue the following command::
+To create a virtual environment, which we name *clamenv* here (but you
+can choose any name you want), issue the following command::
 
   $ virtualenv --python=python3 clamenv
 
@@ -45,7 +45,7 @@ If pip is not yet installed on your system, install it as follows (example for D
 
 
 You can verify the availability of CLAM by opening
-an interactive Python interpreter and writing: ``import clam``\ ”
+an interactive Python interpreter and writing: ``import clam``
 
 LaMachine: a meta-distribution with CLAM
 ---------------------------------------------

docs/source/restapi.rst

@@ -4,16 +4,23 @@ RESTful API specification
 =============================
 
 This appendix provides a full specification of the RESTful interface to
-CLAM:
+CLAM.
+
+
+.. note::
+
+    Note that for each webservice, an auto-generated and human readable RESTful API specification is available at the ``/info/``
+    endpoint which provides a more tailored overview. This info page also presents auto-generated example code for
+    interacting with the webservice.
 
 :Endpoint: ``/``
 :Method: ``GET``
-:Request Parameters:  -
+:Request Parameters:  (none)
 :Response: ``200 - OK`` & CLAM XML, ``401 - Unauthorised``
 
 :Endpoint: ``/[project]/``
 :Method: ``GET``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & CLAM XML, ``401 - Unauthorised``,
   ``404 - Not Found``
 :Description: This returns the current state of the project in
@@ -22,7 +29,7 @@ CLAM:
   Note that errors in parameter validation are encoded in the CLAM XML
   response; the system will still return a 200 response.
 :Method: ``PUT``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``201 - Created``, ``401 - Unauthorised``,
   ``403 - Forbidden`` *(Invalid project ID)*, ``403 - Forbidden`` *(No project name)*
 :Description: This is necessary before attempting to upload any
@@ -56,12 +63,12 @@ CLAM:
 
 :Endpoint: ``/[project]/input/[filename]``
 :Method: ``GET``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & File contents, ``401 - Unauthorised``,
   ``404 - Not Found``
 :Description: Retrieves the specified input file.
 :Method: ``DELETE``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & File contents, ``401 - Unauthorised``,
   ``404 - Not Found``
 :Description: Deletes the specified input file.
@@ -96,27 +103,27 @@ CLAM:
 
 :Endpoint: ``/[project]/output/[filename]``
 :Method: ``GET``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & File contents, ``401 - Unauthorised``,
   ``404 - Not Found``
 :Description: Retrieves the specified output file.
 :Method: ``DELETE``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & File contents, ``401 - Unauthorised``,
   ``404 - Not Found``
 :Description: Deletes the specified output file.
 
 :Endpoint: ``/[project]/output/[filename]/metadata``
 :Method: ``GET``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & CLAM Metadata XML,
   ``401 - Unauthorised``, ``404 - Not Found``
 :Description: Retrieves the metadata for the specified output
   file.
 
 :Endpoint: ``/[project]/input/[filename]/metadata``
 :Method: ``GET``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & CLAM Metadata XML,
   ``401 - Unauthorised``, ``404 - Not Found``
 :Description: Retrieves the metadata for the specified input file.
@@ -129,7 +136,7 @@ CLAM:
 :Description: Offers a single archive, of the desired format,
   including all output files
 :Method: ``DELETE``
-:Request Parameters: -
+:Request Parameters: (none)
 :Response: ``200 - OK`` & File contents, ``401 - Unauthorised``
 :Description: Deletes all output files and resets the project for
   another run.