docs: add guides and summary

docs/ARCHITECTURE.rst

@@ -5,13 +5,17 @@ Architecture
 
     .. uml:: architecture.uml
 
+This program's design resembles a Resource-Method-Representation architecture pattern. This is due to the design choice of making it API-oriented, instead of
+domain-oriented. Therefore 
 
 
-Programming Paradigm
+Router
---------------------
 
-This python package is mainly authored according to a functional programming 
+
-paradigm, however, strictly adhering to said seemed ignorant, since not all 
+Controller
-objects in Python are immutable anyway. Modification of mutable input objects 
+
-are therefore not regarded as side-effects per se, due to the contractual nature
+
-of a function's parameter signature.  
+Model
+
+
+Backend

docs/CONTRIBUTING.rst

@@ -1,7 +1,7 @@
 Contribution Guidelines
 =======================
 
-TO-DO test
+TODO
 
 Prerequisites
 -------------
@@ -13,9 +13,11 @@ You need the following tools to be installed:
 
 .. code-block:: shell
 
-    $ git clone git@bitbucket.org:victorykit/ezcfn.git
+    $ git clone git@bitbucket.org:victorykit/httpaste.git
-    $ cd ezcfn
+    $ cd httpaste
     $ python3 -m pipenv install -d
     $ python3 -m pipenv run tox -e test
     $ python3 -m pipenv run tox -e build
-    $ python3 -m pipenv run tox -e build-docs
+    $ python3 -m pipenv run tox -e docs
+    $ python3 -m pipenv run tox -e lint
+    $ python3 -m pipenv run tox -e format

docs/README.rst

@@ -1,38 +1,41 @@
-httpaste
+httpaste - versatile HTTP pastebin
-========
+==================================
 
 .. only:: readme
 
-    ![](docs/_assets/images/dog-gf2faaf3f6_1920.png)
+    ![](docs/_assets/images/favpng_parrot-royalty-free-cartoon.png)
 
 .. only:: not readme
 
-    .. image:: _assets/images/dog-gf2faaf3f6_1920.png
+    .. image:: _assets/images/favpng_parrot-royalty-free-cartoon.png
 
-Simple and safe pasting over HTTP.
+httpaste is a pastebin application for easily pasting and retrieving data over 
+HTTP from shell environments and web browsers. It is inspired by `sprunge.us`_ 
+and `ix.io`_, but focuses on extendability, advanced security, with little to 
+no trade-off to simplicity. It can be hosted through WSGI, CGI, Fast CGI, or 
+as a standalone evaluation server. It offers multiple storage backends, such as 
+a filesystem backend, SQLite backend, MySQL backend, or MongoDB backend.
 
-httpaste is a pastebin application for easily pasting and retrieving data over HTTP from shell environments and web browsers. It is inspired by sprunge.us and ix.io, but focuses on extendability and advanced security.
+All pastes are being encrypted on the fly and can only be retrieved by an 
+authorized user, either through knowing the paste id of a public paste, or 
+having authentication credentials, as well as the paste id of a private paste. 
+This makes httpaste ideal as a pastebin for sensitive environments such as the 
+Tor network. Authentication credentials are created on-the-fly and don't  require a sign-up process.
 
-public and private pastes are supported. In any case, httpaste provides full anonymity, with each paste being stored encrypted.
+httpaste supports output formatting for syntax highlighting (powered by 
+`pygments`_), as well as MIME type output manipulation, and input encoding. 
+Therefore httpaste can server as an anonymous object storage for small data.
 
-Why
+Minute-based and 'burn-after-read' paste expiration are supported.
----
-
-As a user: Sometimes we say and write stupid things. Things so stupid, that 
-others may even be offended. Others being so offended, that they wish to take 
-legal actions against you. Legal actions which infringe upon your rights for
- privacy. Who is the others? Well, it's the 
- 
-Public pastes: Only people you share the paste id with are able to view the paste. Public pastes aren't indexed publicly, so Public pastes are encrypted with their paste id and the paste id is only
-stored as a hash. Therefore the httpaste application hoster is unable to view any pastes, unless he maliciously logs any of the HTTP requests.
 
+httpaste focuses on security through cryptography, making it a computationally intensive application.
 
 .. include:: guide/get-started.rst
 
 Documentation
 -------------
 
-The documentation can be found under `<https://victorykit.bitbucket.io/taskdog/>`_.
+The documentation can be found under `<https://victorykit.bitbucket.io/httpaste/>`_.
 
 
 Licensing
@@ -53,9 +56,17 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program. If not, see <https://www.gnu.org/licenses/>.
 
+This program uses licensed third-party software.
+
+
 .. toctree::
     :maxdepth: 1
     :caption: More Information
 
     ARCHITECTURE
     CONTRIBUTING
+
+.. _ix.io: http://ix.io/
+.. _sprunge.us: http://sprunge.us
+.. _pygments: https://pygments.org/
+.. _icon: https://favpng.com/png_view/parrot-parrot-royalty-free-cartoon-png/gps7HM42

docs/conf.py

@@ -21,7 +21,7 @@ extensions = [
     'sphinxcontrib.plantuml',
     'sphinxarg.ext',
     'sphinx.ext.viewcode',
-    'sphinx_autodoc_typehints'
+    'sphinx_autodoc_typehints',
 ]
 
 templates_path = ['_templates']

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 
+SQLite
-Base16 and provide an encoding specifier.
+------
 
-.. code-block:: shell
+.. autoclass:: httpaste.backend.sqlite.Parameters
+    :members:
 
-    $ cat my.pdf | base64 | curl "http://localhost:8080/paste/public?encoding=base64"
+Filesystem
-    http://localhost:8080/paste/public/5Rt3E3n6
+----------
 
-When getting pastes, you may provide a MIME type, if a client deduces the encoding by looking at the HTTP 'Content-Type' header.
+.. autoclass:: httpaste.backend.file.Parameters
-
+    :members:
-     $ curl "https://p.victoryk.it/paste/public/5Rt3E3n6?mime=application/pdf"

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=<-' \
+    $ echo 'My first private paste' | curl -F 'data=<-' -u myusername:mypassword http://localhost:8080/paste/private
-        -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=<-' \ 
+    $ echo 'My first public paste' | curl -F 'data=<-' http://localhost:8080/paste/public
-        http://localhost:8080/paste/public
     http://localhost:8080/paste/public/X4L39J
 
+
 Retrieve a Public Paste
-------------------------
+""""""""""""""""""""""""
 
 .. code-block:: shell
 

docs/index.rst

@@ -2,9 +2,12 @@
 
 .. toctree::
     :maxdepth: 1
-    :caption: Contents:
+    :caption: Guides
 
     guide/get-started
+    guide/advanced-usage
+    guide/backend
+    guide/cli