Update how we write and build our documentation

betamaxpy · Mar 13, 2018 · ae2f75c · ae2f75c
1 parent cf6aefe
commit ae2f75c
Show file tree

Hide file tree

Showing 17 changed files with 39 additions and 172 deletions.
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,6 @@
+sphinx>=1.3.0
+pytest
+betamax_matchers
+betamax_serializers
+requests
+readme
diff --git a/docs/api.rst → docs/source/api.rst b/docs/api.rst → docs/source/api.rst
diff --git a/docs/cassettes.rst → docs/source/cassettes.rst b/docs/cassettes.rst → docs/source/cassettes.rst
diff --git a/docs/conf.py → docs/source/conf.py b/docs/conf.py → docs/source/conf.py
@@ -14,14 +14,10 @@
 import os
 import sys
 
-# This environment variable makes decorators not decorate functions, so their
-# signatures in the generated documentation are still correct
-os.environ['GENERATING_DOCUMENTATION'] = "betamax"
-
 # 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.
-sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('../../src'))
 import betamax
 
 # -- General configuration ---------------------------------------------------
@@ -47,7 +43,7 @@
 
 # General information about the project.
 project = u'Betamax'
-copyright = u'2013-2015 - Ian Cordasco'
+copyright = u'2013-2018 - Ian Stapleton Cordasco'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -70,7 +66,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['build']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents #default_role = None
@@ -188,7 +184,7 @@
 # [howto/manual]).
 latex_documents = [
     ('index', 'betamax.tex', u'Betamax Documentation',
-     u'Ian Cordasco', 'manual'),
+     u'Ian Stapleton Cordasco', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -221,7 +217,7 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'betamax', u'Betamax Documentation',
-     [u'Ian Cordasco'], 1)
+     [u'Ian Stapleton Cordasco'], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -242,7 +238,7 @@
 
 # Intersphinx configuration
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3.4',
+    'python': ('https://docs.python.org/3.6',
                (None, 'python-inv.txt')),
     'requests': ('http://docs.python-requests.org/en/latest',
                  (None, 'requests-inv.txt')),

diff --git a/docs/configuring.rst → docs/source/configuring.rst b/docs/configuring.rst → docs/source/configuring.rst
diff --git a/docs/implementation_details.rst → docs/source/implementation_details.rst b/docs/implementation_details.rst → docs/source/implementation_details.rst
diff --git a/docs/index.rst → docs/source/index.rst b/docs/index.rst → docs/source/index.rst
@@ -1,4 +1,4 @@
-.. include:: ../README.rst
+.. include:: ../../README.rst
 
 Contents of Betamax's Documentation
 ===================================

diff --git a/docs/integrations.rst → docs/source/integrations.rst b/docs/integrations.rst → docs/source/integrations.rst
diff --git a/docs/introduction.rst → docs/source/introduction.rst b/docs/introduction.rst → docs/source/introduction.rst
@@ -73,13 +73,13 @@ Recording Your First Cassette
 Let's make a file named ``our_first_recorded_session.py``. Let's add the
 following to our file:
 
-.. literalinclude:: ../examples/our_first_recorded_session.py
+.. literalinclude:: ../../examples/our_first_recorded_session.py
     :language: python
 
 If we then run our script, we'll see that a new file is created in our
 specified cassette directory. It should look something like:
 
-.. literalinclude:: ../examples/cassettes/our-first-recorded-session.json
+.. literalinclude:: ../../examples/cassettes/our-first-recorded-session.json
     :language: javascript
 
 Now, each subsequent time that we run that script, we will use the recorded
@@ -92,7 +92,7 @@ Most times we cannot isolate our tests to a single request at a time, so we'll
 have cassettes that make multiple requests. Betamax can handle these with
 ease, let's take a look at an example.
 
-.. literalinclude:: ../examples/more_complicated_cassettes.py
+.. literalinclude:: ../../examples/more_complicated_cassettes.py
     :language: python
 
 Before we run this example, we have to install a new package:
@@ -112,7 +112,7 @@ provided by the ``betamax-serializers`` package on PyPI that can serialize and
 deserialize cassette data into JSON while allowing it to be easily human
 readable and pretty. Let's see the results:
 
-.. literalinclude:: ../examples/cassettes/more-complicated-cassettes.json
+.. literalinclude:: ../../examples/cassettes/more-complicated-cassettes.json
     :language: javascript
 
 This makes the cassette easy to read and helps us recognize that requests and

diff --git a/docs/long_term_usage.rst → docs/source/long_term_usage.rst b/docs/long_term_usage.rst → docs/source/long_term_usage.rst
@@ -11,7 +11,7 @@ Adding New Requests to a Cassette
 Let's reuse an example. Specifically let's reuse our
 :file:`examples/more_complicated_cassettes.py` example.
 
-.. literalinclude:: ../examples/more_complicated_cassettes.py
+.. literalinclude:: ../../examples/more_complicated_cassettes.py
     :language: python
 
 Let's add a new ``POST`` request in there:
@@ -30,12 +30,12 @@ the URI and the Method. So Betamax will find a matching request/response pair
 for ``("POST", "https://httpbin.org/post?id=20")`` and reuse it. So now we
 need to update how we use Betamax so it will match using the ``body`` as well:
 
-.. literalinclude:: ../examples/more_complicated_cassettes_2.py
+.. literalinclude:: ../../examples/more_complicated_cassettes_2.py
     :language: python
 
 Now when we run that we should see something like this:
 
-.. literalinclude:: ../examples/more_complicated_cassettes_2.traceback
+.. literalinclude:: ../../examples/more_complicated_cassettes_2.traceback
     :language: pytb
 
 This is what we do expect to see. So, how do we fix it?

diff --git a/docs/matchers.rst → docs/source/matchers.rst b/docs/matchers.rst → docs/source/matchers.rst
@@ -65,22 +65,22 @@ Each request matcher has to inherit from ``betamax.BaseMatcher`` and implement
 
 Some examples of matchers are in the source reproduced here:
 
-.. literalinclude:: ../betamax/matchers/headers.py
+.. literalinclude:: ../../src/betamax/matchers/headers.py
     :language: python
 
-.. literalinclude:: ../betamax/matchers/host.py
+.. literalinclude:: ../../src/betamax/matchers/host.py
     :language: python
 
-.. literalinclude:: ../betamax/matchers/method.py
+.. literalinclude:: ../../src/betamax/matchers/method.py
     :language: python
 
-.. literalinclude:: ../betamax/matchers/path.py
+.. literalinclude:: ../../src/betamax/matchers/path.py
     :language: python
 
-.. literalinclude:: ../betamax/matchers/path.py
+.. literalinclude:: ../../src/betamax/matchers/path.py
     :language: python
 
-.. literalinclude:: ../betamax/matchers/uri.py
+.. literalinclude:: ../../src/betamax/matchers/uri.py
     :language: python
 
 When you have finished writing your own matcher, you can instruct betamax to 

diff --git a/docs/record_modes.rst → docs/source/record_modes.rst b/docs/record_modes.rst → docs/source/record_modes.rst
@@ -26,7 +26,7 @@ to log all HTTP requests.
 
 Given our file, ``examples/record_modes/all/example.py``,
 
-.. literalinclude:: ../examples/record_modes/all/example.py
+.. literalinclude:: ../../examples/record_modes/all/example.py
     :language: python
 
 Every time we run it, our cassette 
@@ -49,12 +49,12 @@ Given our file, ``examples/record_modes/new_episodes/example_original.py``,
 with which we have already recorded 
 ``examples/record_modes/new_episodes/new-episodes-example.json``
 
-.. literalinclude:: ../examples/record_modes/new_episodes/example_original.py
+.. literalinclude:: ../../examples/record_modes/new_episodes/example_original.py
     :language: python
 
 If we then run ``examples/record_modes/new_episodes/example_updated.py``
 
-.. literalinclude:: ../examples/record_modes/new_episodes/example_updated.py
+.. literalinclude:: ../../examples/record_modes/new_episodes/example_updated.py
     :language: python
 
 The new request at the end of the file will be added to the cassette without 
@@ -75,17 +75,17 @@ Given our file, ``examples/record_modes/none/example_original.py``, with a
 cassette that already has interactions recorded in 
 ``examples/record_modes/none/none-example.json``
 
-.. literalinclude:: ../examples/record_modes/none/example_original.py
+.. literalinclude:: ../../examples/record_modes/none/example_original.py
     :language: python
 
 If we then run ``examples/record_modes/none/example_updated.py``
 
-.. literalinclude:: ../examples/record_modes/none/example_updated.py
+.. literalinclude:: ../../examples/record_modes/none/example_updated.py
     :language: python
 
 We'll see an exception indicating that new interactions were prevented:
 
-.. literalinclude:: ../examples/record_modes/none/example_updated.traceback
+.. literalinclude:: ../../examples/record_modes/none/example_updated.traceback
     :language: pytb
 
 Once
@@ -105,21 +105,21 @@ or whatever).
 
 If we have a file, ``examples/record_modes/once/example_original.py``,
 
-.. literalinclude:: ../examples/record_modes/once/example_original.py
+.. literalinclude:: ../../examples/record_modes/once/example_original.py
     :language: python
 
 And we run it, we'll see a cassette named 
 ``examples/record_modes/once/once-example.json`` has been created.
 
 If we then run ``examples/record_modes/once/example_updated.py``,
 
-.. literalinclude:: ../examples/record_modes/once/example_updated.py
+.. literalinclude:: ../../examples/record_modes/once/example_updated.py
     :language: python
 
 We'll see an exception similar to the one we see when using the ``'none'`` 
 record mode.
 
-.. literalinclude:: ../examples/record_modes/once/example_updated.traceback
+.. literalinclude:: ../../examples/record_modes/once/example_updated.traceback
     :language: pytb
 
 

diff --git a/docs/serializers.rst → docs/source/serializers.rst b/docs/serializers.rst → docs/source/serializers.rst
@@ -31,7 +31,7 @@ implement three methods:
 
 Here's the default (JSON) serializer as an example:
 
-.. literalinclude:: ../betamax/serializers/json_serializer.py
+.. literalinclude:: ../../src/betamax/serializers/json_serializer.py
     :language: python
 
 

diff --git a/docs/third_party_packages.rst → docs/source/third_party_packages.rst b/docs/third_party_packages.rst → docs/source/third_party_packages.rst
@@ -152,7 +152,7 @@ for you.
 
 This will give us a pretty-printed cassette like:
 
-.. literalinclude:: ../examples/cassettes/more-complicated-cassettes.json
+.. literalinclude:: ../../examples/cassettes/more-complicated-cassettes.json
     :language: js
 
 .. links

diff --git a/docs/usage_patterns.rst → docs/source/usage_patterns.rst b/docs/usage_patterns.rst → docs/source/usage_patterns.rst
diff --git a/tox.ini b/tox.ini
@@ -41,15 +41,10 @@ commands =
 
 [testenv:docs]
 deps =
-    sphinx>=1.3.0
-    pytest
-    betamax_matchers
-    betamax_serializers
-    requests
-    readme
+    -rdocs/requirements.txt
     .
 commands =
-    sphinx-build -W -E -c docs -b html docs/ docs/_build/html
+    sphinx-build -E -W -c docs/source/ -b html docs/source/ docs/build/html
 
 [testenv:readme]
 deps =