Documentation update for new functionality

Also a slight tweak to allow specific cards from a pile to be returned to the main deck, mirroring the functionality for drawn cards.

deck/templates/docs.html

@@ -241,9 +241,10 @@ <h3>Response:</h3>
 <h2 class="section-header" id="reshuffle">Reshuffle the Cards:</h2>
 <pre>
 {{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/shuffle/
+{{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/shuffle/?remaining=true
 </pre>
 
-<p>Don't throw away a deck when all you want to do is shuffle. Include the <var>deck_id</var> on your call to shuffle your cards. Don't worry about reminding us how many decks you are playing with.</p>
+<p>Don't throw away a deck when all you want to do is shuffle. Include the <var>deck_id</var> on your call to shuffle your cards. Don't worry about reminding us how many decks you are playing with. Adding the <var>remaining=true</var> parameter will only shuffle those cards remaining in the main stack, leaving any piles or drawn cards alone.</p>
 <br>
 <h3>Response:</h3>
 <pre>
@@ -378,8 +379,9 @@ <h2 class="section-header" id="draw-from-pile">Drawing from Piles</h2>
 {{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/pile/&lt;&lt;pile_name&gt;&gt;/draw/?cards=AS
 {{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/pile/&lt;&lt;pile_name&gt;&gt;/draw/?count=2
 {{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/draw/bottom/
+{{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/draw/random/
 </pre>
-<p>Specify the cards that you want to draw from the pile. The default is to just draw off the top of the pile (it's a <a href="http://en.wikipedia.org/wiki/Stack_(abstract_data_type)">stack</a>). Or add the <var>bottom</var> parameter to the URL to draw from the bottom.</p>
+<p>Specify the cards that you want to draw from the pile. The default is to just draw off the top of the pile (it's a <a href="http://en.wikipedia.org/wiki/Stack_(abstract_data_type)">stack</a>). Add <var>/bottom/</var> to the URL to draw from the bottom or <var>/random/</var> to draw random cards - both of these also accept the <var>count</var> parameter.</p>
 
 <h3>Response:</h3>
 <pre>
@@ -403,6 +405,31 @@ <h3>Response:</h3>
 }
 </pre>
 
+<h2 class="section-header" id="return">Returning cards to the deck:</h2>
+<pre>
+{{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/return/
+{{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/pile/&lt;&lt;pile_name&gt;&gt;/return/
+{{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/return/?cards=AS,2S
+{{ request.scheme }}://{{ request.META.HTTP_HOST }}/api/deck/&lt;&lt;deck_id&gt;&gt;/pile/&lt;&lt;pile_name&gt;&gt;/return/?cards=AS,2S
+</pre>
+
+<p>Use this call to return cards which have been drawn or cards from a pile back to the main deck to re-use. Both versions can take the <var>cards</var> parameter for a list of cards to return (if valid).</p>
+<br>
+<h3>Response:</h3>
+<pre>
+{
+ "success": true,
+ "deck_id": "3p40paa87x90",
+ "shuffled": true,
+ "remaining": 52
+ "piles": {
+ "discard": {
+ "remaining": 0
+ }
+ }
+}
+</pre>
+
 {% if v == 1 %}
 <h3 class="section-header text-center" style="font-weight: 300;">Lastly, I am working on a kids' book, Computer Engineering for Babies. So if you know any babies or anyone else that enjoys gates buttons & LEDs, then check it out!</h3>
 <a href="https://computerengineeringforbabies.com/home?ss_source=ptads&ss_campaign_name=spades&ss_ad_id=var1" style="color:#fff300;">

deck/views.py

@@ -174,10 +174,19 @@ def return_pile_to_deck(request, key, pile):
  deck = Deck.objects.get(key=key)
  except Deck.DoesNotExist:
  return deck_id_does_not_exist()
+
+ cards_specified = _get_request_var(request, 'cards', None)
 
  if deck.piles and pile in deck.piles:
- deck.stack.extend(deck.piles[pile])
- deck.piles[pile] = []
+ if cards_specified is None:
+ # Return all cards from the pile to the deck
+ deck.stack.extend(deck.piles[pile])
+ deck.piles[pile] = []
+ else:
+ cards_specified = cards_specified.upper()
+ cards_specified = [x for x in cards_specified.split(',') if x in deck.piles[pile]] # check that the cards are in the pile
+ deck.stack.extend(cards_specified) # put specified cards back into deck.stack
+ deck.piles[pile] = [x for x in deck.piles[pile] if x not in cards_specified] # remove sepcified cards
  deck.save()
 
  piles = {}