docs: add guides and summary

docs/guide/advanced-usage.rst

@@ -1,8 +1,8 @@
 Advanced Usage
 ==============
 
-Binary Pastes
--------------
+Binary Data
+-----------
 
 httpaste supports encoding. Encode your data as Base64, Base85, Base32, or 
 Base16 and provide an encoding specifier.
@@ -14,4 +14,56 @@ Base16 and provide an encoding specifier.
 
 When getting pastes, you may provide a MIME type, if a client deduces the encoding by looking at the HTTP 'Content-Type' header.
 
+.. code-block:: shell
+
      $ curl "https://p.victoryk.it/paste/public/5Rt3E3n6?mime=application/pdf"
+
+Custom Expiration
+-----------------
+
+Set a paste's lifetime to make it expire after a specified amount of time. The 
+lifetime must be provided in minutes and cannot be less than 1. A lifetime of
+0 will evaluate to a lifetime 1.
+
+.. code-block:: shell
+
+    $ echo "My paste expires after reading" | curl "http://localhost:8080/paste/public?lifetime=360" -F "data=<-"
+    http://localhost:8080/paste/public/5Rt3E3n6
+
+Burn-After-Read Expiration
+--------------------------
+
+Set a paste's lifetime to <0 to make it expire right after reading
+
+.. code-block:: shell
+
+    $ echo "My paste expires after reading" | curl "http://localhost:8080/paste/public?lifetime=-1" -F "data=<-"
+    http://localhost:8080/paste/public/5Rt3E3n6
+
+.. code-block:: shell
+
+    $ curl http://localhost:8080/paste/public/5Rt3E3n6
+    My paste expires after reading
+    $ curl http://localhost:8080/paste/public/5Rt3E3n6
+    {"detail":"Paste expired","status":410,"title":"Gone"}
+
+Syntax Higlighting
+------------------
+
+You can apply syntax highlighting to a multitude of formats. Consult the pygments documentation for valid specifiers.
+
+.. code-block:: shell
+
+    $ curl "http://localhost:8080/paste/public/5Rt3E3n6?syntax=terraform"
+
+Highlighting, by default, will be formatted for 256 color terminals. You can also change the formatting.
+
+.. code-block:: shell
+
+    $ curl "http://localhost:8080/paste/public/5Rt3E3n6?syntax=terraform&format=html"
+
+You can also add line numbers to the output.
+
+.. code-block:: shell
+
+    $ curl "http://localhost:8080/paste/public/5Rt3E3n6?syntax=terraform&format=html&linenos=true"

docs/guide/backend.rst

@@ -1,17 +1,16 @@
 Backend
 =======
 
-Binary Pastes
--------------
+The backend can be configured within the `[backend]` section of the configuration file.
 
-httpaste supports encoding. Encode your data as Base64, Base85, Base32, or 
-Base16 and provide an encoding specifier.
+SQLite
+------
 
-.. code-block:: shell
+.. autoclass:: httpaste.backend.sqlite.Parameters
+    :members:
 
-    $ cat my.pdf | base64 | curl "http://localhost:8080/paste/public?encoding=base64"
-    http://localhost:8080/paste/public/5Rt3E3n6
+Filesystem
+----------
 
-When getting pastes, you may provide a MIME type, if a client deduces the encoding by looking at the HTTP 'Content-Type' header.
-
-     $ curl "https://p.victoryk.it/paste/public/5Rt3E3n6?mime=application/pdf"
+.. autoclass:: httpaste.backend.file.Parameters
+    :members:

docs/guide/cli.rst

@@ -0,0 +1,7 @@
+Command-Line Interface
+======================
+
+.. argparse::
+   :module: httpaste.__main__
+   :func: parser
+   :prog: httpaste

docs/guide/cli.rstas

@@ -1,2 +0,0 @@
-Get Started
-===========

docs/guide/get-started.rst

@@ -1,68 +1,68 @@
 Get Started
 ===========
 
-Installation
-------------
+Install
+"""""""
 
 .. code-block:: shell
 
     $ python3 -m pip install httpaste-victorykit
     $ httpaste --help
 
-Create configuration
---------------------
+
+Create Configuration
+""""""""""""""""""""
 
 .. code-block:: shell
 
     $ httpaste default-config --dump myconfig.ini
 
-Run a local test server
------------------------
+.. note::
+    The default configuration creates an in-memory SQLite backend, which is not 
+    suitable for WWW deployments. Visit `backend`, for more 
+    information on configuring the backend.
+
+
+Run a Local Evaluation Server
+"""""""""""""""""""""""""""""
 
 .. code-block:: shell
 
     $ httpaste standalone --config myconfig.ini --port 8080
-    * Serving Flask app 'httpaste' (lazy loading)                        
-    * Environment: production                                                                                                                                   
-      WARNING: This is a development server. Do not use it in a production deployment.
-      Use a production WSGI server instead.                                                                                                                     
-    * Debug mode: off                                                            
-    * Running on all addresses.                                                  
-      WARNING: This is a development server. Do not use it in a production deployment.
-    * Running on http://localhost:8080/ (Press CTRL+C to quit)
+
 
 Publish a Private Paste
------------------------
+"""""""""""""""""""""""
 
 .. code-block:: shell
 
-    $ echo 'My first private paste' | curl -F 'data=<-' \
-        -u myusername:mypassword \ 
-        http://localhost:8080/paste/private
+    $ echo 'My first private paste' | curl -F 'data=<-' -u myusername:mypassword http://localhost:8080/paste/private
     http://localhost:8080/paste/private/UALUA9
 
 .. note::
     If the user does not exist, they will be created upon authentication.
 
+
 Retrieve a Private Paste
-------------------------
+""""""""""""""""""""""""
 
 .. code-block:: shell
 
     $ curl -u myusername:mypassword http://localhost:8080/paste/private/UALUA9
     My first private paste
 
+
 Publish a Public Paste
------------------------
+""""""""""""""""""""""
 
 .. code-block:: shell
 
-    $ echo 'My first public paste' | curl -F 'data=<-' \ 
-        http://localhost:8080/paste/public
+    $ echo 'My first public paste' | curl -F 'data=<-' http://localhost:8080/paste/public
     http://localhost:8080/paste/public/X4L39J
 
+
 Retrieve a Public Paste
-------------------------
+""""""""""""""""""""""""
 
 .. code-block:: shell