Merge pull request #11 from econchick/master

RC 0.1.3 - Update docs

.travis.yml

@@ -17,6 +17,7 @@ after_success:
 - coveralls
 notifications:
   email: false
+  irc: "chat.freenode.net#ramlfications"
   slack:
     secure: RGdJmcQiapxCZWALwbogYykeuqUWhKgFtMR7JgRqPg/swcqbvD2rWYkT7eqUBrUldU7dTFhXt0RRqBf6J5vm4WcvkY5heQ4OpTi7R4itIiMLPndN24eG//PaOMhqrUyjkCsrWb0B7nuGRXmnH0C5xkPS/Dz1acugPG7zzXBKbKk=
 deploy:

README.rst

@@ -107,6 +107,12 @@ or::
 Then within ``ramlfications/docs/_build`` you can open the index.html page in your browser.
 
 
+Still have issues?
+^^^^^^^^^^^^^^^^^^
+
+Feel free to drop by ``#ramlfications`` on Freenode (`webchat`_) or ping via `Twitter`_.
+"roguelynn" is the maintainer, a.k.a `econchick`_ on GitHub, and based in San Fran.
+
 
 .. _pip: https://pip.pypa.io/en/latest/installing.html#install-pip
 .. _PyPI: https://pypi.python.org/project/ramlfications/
@@ -117,3 +123,6 @@ Then within ``ramlfications/docs/_build`` you can open the index.html page in yo
 .. _`Read the Docs site`: https://ramlfications.readthedocs.org
 .. _`usage`: http://ramlfications.readthedocs.org/en/latest/usage.html
 .. _`How to Contribute`: http://ramlfications.readthedocs.org/en/latest/contributing.html
+.. _`webchat`: http://webchat.freenode.net?channels=%23ramlfications&uio=ND10cnVlJjk9dHJ1ZQb4
+.. _`econchick`: https://github.com/econchick
+.. _`Twitter`: https://twitter.com/roguelynn

docs/changelog.rst

@@ -1,6 +1,21 @@
 Changelog
 =========
 
+
+0.1.3 (2015-05-14)
+------------------
+
+Added:
+
+- New ``#ramlfications`` channel on `freenode`_ (web chat link)! Come chat, I'm lonely.
+- Documentation for configuration and the ``update`` command.
+
+Fixed:
+
+- Handle recursive/cyclical ``!includes`` in RAML files for now (`PR`_)
+- Encoding issues from upgrading to tox 2.0
+- ``tests/test_utils.py`` would create ``ramlfications/data/supported_mime_types.json``; now mocked out.
+
 0.1.2 (2015-04-21)
 ------------------
 
@@ -19,3 +34,7 @@ New:
 0.1.0a1 (2015-04-18)
 --------------------
 Initial alpha release of ``ramlfications``\!
+
+
+.. _`PR`: https://github.com/spotify/ramlfications/pull/8
+.. _`freenode`: http://webchat.freenode.net?channels=%23ramlfications&uio=ND10cnVlJjk9dHJ1ZQb4

docs/conf.py

@@ -46,6 +46,22 @@ def find_version(*file_paths):
         return version_match.group(1)
     raise RuntimeError("Unable to find version string.")
 
+
+def find_latest_release_date():
+    """
+    Build a date string from the latest release logged in ``changelog.rst``
+    """
+    changelog = read("changelog.rst")
+    # format of either YYYY-MM-DD or YYYY/MM/DD
+    date_regex = re.compile("(\d{4}[-/]\d{2}[-/]\d{2})")
+    date_match = date_regex.findall(changelog)[0]
+    if date_match:
+        release_date = datetime.datetime.strptime(date_match, "%Y-%m-%d")
+        fmt_release_date = release_date.strftime("%b %-d, %Y")
+        return fmt_release_date
+    raise RuntimeError("Unable to find latest release date in changelog.rst")
+
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -103,7 +119,7 @@ def find_version(*file_paths):
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#today = ''
+today = find_latest_release_date()
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 

docs/config.rst

@@ -0,0 +1,121 @@
+Configuration
+=============
+
+.. _supported:
+
+Supported
+---------
+
+In support of the `RAML spec`_, ``ramlfications`` will automatically support
+the following:
+
+RAML Versions
+^^^^^^^^^^^^^
+
+| **Config variable**: ``raml_versions``
+| **Config type**: list of strings
+| **Supported**: ``0.8``
+|
+
+
+HTTP Methods
+^^^^^^^^^^^^
+| **Config variable**: ``http_methods``
+| **Config type**: list of strings
+| **Supported**: ``GET``, ``POST``, ``PUT``, ``DELETE``, ``PATCH``, ``HEAD``, ``OPTIONS``, ``TRACE``, ``CONNECT``
+|
+
+Authentication Schemes
+^^^^^^^^^^^^^^^^^^^^^^
+
+| **Config variable**: ``auth_schemes``
+| **Config type**: list of strings
+| **Supported**: OAuth 1.0, OAuth 2.0, Basic Authentication, Digest Authentication
+|
+
+HTTP Response Codes
+^^^^^^^^^^^^^^^^^^^
+
+| **Config variable**: ``resp_codes``
+| **Config type**: list of integers
+| **Supported**: From Python stdlib ``BaseHTTPServer``
+|  ``100``, ``101``,
+|  ``200``, ``201``, ``202``, ``203``, ``204``, ``205``, ``206``,
+|  ``300``, ``301``, ``302``, ``303``, ``304``, ``305``, ``307``,
+|  ``400``, ``401``, ``402``, ``403``, ``404``, ``405``, ``406``, ``407``, ``408``, ``409``, ``410``, ``411``, ``412``, ``413``, ``414``, ``415``, ``416``, ``417``,
+|  ``500``, ``501``, ``502``, ``503``, ``504``, ``505``
+|
+
+Protocols
+^^^^^^^^^
+
+| **Config variable**: ``protocols``
+| **Config type**: list of strings
+| **Supported**: ``HTTP``, ``HTTPS``
+|
+
+MIME Media Types
+^^^^^^^^^^^^^^^^
+
+| **Config variable**: ``media_types``
+| **Config type**: list of strings that fit the regex defined under `default media type`_: ``application\/[A-Za-z.-0-1]*+?(json|xml)``
+| **Supported**: MIME media types that the package supports can be found on `GitHub`_ and is up to date as of the time of this release (|today|).
+|
+
+.. note::
+    If you would like to update your own setup with the latest `IANA`_ supported MIME media types, refer to :doc:`usage`.
+
+
+User-specified
+--------------
+
+You may define additional values beyond what ``ramlfications`` already supports above.
+
+To do so, create your own ``ini`` file with a ``[custom]`` section.
+
+Then add the attributes defined :ref:`above <supported>` that you want to support.
+You can **only** add support to the configuration values explained above.
+
+.. warning::
+
+    Additionally supported values defined in your configuration will only **add** to the values
+    that ``ramlfications`` will validate against; it will **not** overwrite values that the
+    ``ramlfications`` supports as defined in the `RAML spec`_.
+
+An example ``config.ini`` file::
+
+    [custom]
+    raml_versions = 0.9, 1.0
+    http_methods = foo, bar
+    auth_schemes = oauth_3_0, my_auth
+    media_types = application/vnd.foobar.v2
+    protocols = FTP
+    resp_codes = 429, 440
+
+
+Usage
+^^^^^
+
+To use your configuration from within Python:
+
+.. code-block:: python
+
+    >>> from ramlfications import parse, validate
+    >>> RAML_FILE = "path/to/api.raml"
+    >>> CONFIG_FILE = "path/to/api.ini"
+    >>> api = parse(RAML_FILE, CONFIG_FILE)
+    >>> validate(RAML_FILE, CONFIG_FILE)
+    >>>
+
+To use via the command line:
+
+.. code-block:: bash
+
+    $ ramlfications validate --config path/to/api.ini path/to/api.raml
+    $ ramlfications tree --config path/to/api.ini path/to/api.raml
+
+
+.. _`RAML spec`: http://raml.org/spec.html
+.. _`default media type`: http://raml.org/spec.html#default-media-type
+.. _IANA: https://www.iana.org/assignments/media-types/media-types.xml
+.. _GitHub: https://github.com/spotify/ramlfications/blob/master/ramlfications/data/supported_mime_types.json

docs/index.rst

@@ -16,6 +16,7 @@ User's Guide
    installation
    usage
    extendedusage
+   config
    api