chore: docs updated

3YOURMIND · Apr 12, 2022 · a821496 · a821496
1 parent 280eb58
commit a821496
Show file tree

Hide file tree

Showing 17 changed files with 568 additions and 212 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
 # push-to-3yourmind
+
 A Python SDK library to work with 3YOURMIND's platform API. It enables you to manage user profile
 information, push 3D Files, manipulate baskets, lines, get pricing information, place Orders 
 and Catalog Items.
@@ -19,31 +20,64 @@ Open `/admin/auth/user/`, and click "Create token" in the user list.
 
 ## Usage
 
+### First, initialize API class
+
 ```python
 from push_to_3yourmind import PushTo3YourmindAPI
 client = PushTo3YourmindAPI(
     access_token="QWERTY123456789", 
     base_url="http://<domain-name>",
 )
+```
 
+### Get or set current user's info 
+
+```python
 profile_info = client.my_profile.get_profile()
 my_preferences = client.my_profile.get_preferences()
 client.my_profile.set_preferences(currency="USD", language="de")
 # or
 client.my_profile.set_preferences(language="en")
 # or
 client.my_profile.set_preferences(unit="inch")
+```
+
+### Explore User Panel's API
 
+```python
 # get current user's basket list
 baskets = client.user_panel.get_baskets()
 # or 
 basket = client.user_panel.get_basket(basket_id=6)
+```
 
+### Do more with a single API call
+
+```python
+client.user_panel.create_line_with_cad_file_and_product(
+    basket_id=4,
+    cad_file="/path/to/the/cad_file.stl",
+    product_id=3,
+    quantity=1,
+)
 ```
 
 # Usage Guide
 
-[link](https://3yourmind.github.io/push-to-3yourmind/)
+[Creating a basket, placing an order](https://3yourmind.github.io/push-to-3yourmind/api/user_panel.html)
+
+[User profile management](https://3yourmind.github.io/push-to-3yourmind/api/my_profile.html)
+
+[Common API](https://3yourmind.github.io/push-to-3yourmind/api/common.html)
+
+[there is more](https://3yourmind.github.io/push-to-3yourmind/)
+
+
+# Documentation generation
+
+    poetry install
+    poetry shell
+    make documentation
 
 # @
 

diff --git a/docs/api/base.html b/docs/api/base.html
@@ -41,14 +41,15 @@ <h1 class="title">Module <code>push_to_3yourmind.api.base</code></h1>
 
 class BaseAPI:
     &#34;&#34;&#34;
-    Base class for all namespaced API methods.
+    Base class for all namespaced API methods. Not to be instantiated directly.
     &#34;&#34;&#34;
 
     def __init__(self, access_token: str, base_url: str):
         &#34;&#34;&#34;
-
-        :param access_token:
-        :param base_url:
+        Args:
+            access_token: to create a token, open `/admin/auth/user/`, and click
+                &#34;Create token&#34; in the user list.
+            base_url: application URL, ex. https://app.3yourmind.com
         &#34;&#34;&#34;
         self._api_prefix = &#34;api/v2.0&#34;
         self._access_token = access_token
@@ -109,12 +110,14 @@ <h1 class="title">Module <code>push_to_3yourmind.api.base</code></h1>
             else:
                 response_payload = &#34;&#34;
 
-            if response.status_code == 404:
-                raise exceptions.ObjectNotFound(response_payload)
+            if response.status_code == 400:
+                raise exceptions.BadRequest(response_payload)
             elif response.status_code == 401:
                 raise exceptions.Unauthorized(response_payload)
-            elif response.status_code == 400:
-                raise exceptions.BadRequest(response_payload)
+            elif response.status_code == 403:
+                raise exceptions.AccessDenied(response_payload)
+            elif response.status_code == 404:
+                raise exceptions.ObjectNotFound(response_payload)
             elif response.status_code == 405:
                 raise exceptions.MethodNotAllowed(response_payload)
             return response_payload
@@ -142,23 +145,30 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <span>(</span><span>access_token: str, base_url: str)</span>
 </code></dt>
 <dd>
-<div class="desc"><p>Base class for all namespaced API methods.</p>
-<p>:param access_token:
-:param base_url:</p></div>
+<div class="desc"><p>Base class for all namespaced API methods. Not to be instantiated directly.</p>
+<h2 id="args">Args</h2>
+<dl>
+<dt><strong><code>access_token</code></strong></dt>
+<dd>to create a token, open <code>/admin/auth/user/</code>, and click
+"Create token" in the user list.</dd>
+<dt><strong><code>base_url</code></strong></dt>
+<dd>application URL, ex. <a href="https://app.3yourmind.com">https://app.3yourmind.com</a></dd>
+</dl></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class BaseAPI:
     &#34;&#34;&#34;
-    Base class for all namespaced API methods.
+    Base class for all namespaced API methods. Not to be instantiated directly.
     &#34;&#34;&#34;
 
     def __init__(self, access_token: str, base_url: str):
         &#34;&#34;&#34;
-
-        :param access_token:
-        :param base_url:
+        Args:
+            access_token: to create a token, open `/admin/auth/user/`, and click
+                &#34;Create token&#34; in the user list.
+            base_url: application URL, ex. https://app.3yourmind.com
         &#34;&#34;&#34;
         self._api_prefix = &#34;api/v2.0&#34;
         self._access_token = access_token
@@ -219,12 +229,14 @@ <h2 class="section-title" id="header-classes">Classes</h2>
             else:
                 response_payload = &#34;&#34;
 
-            if response.status_code == 404:
-                raise exceptions.ObjectNotFound(response_payload)
+            if response.status_code == 400:
+                raise exceptions.BadRequest(response_payload)
             elif response.status_code == 401:
                 raise exceptions.Unauthorized(response_payload)
-            elif response.status_code == 400:
-                raise exceptions.BadRequest(response_payload)
+            elif response.status_code == 403:
+                raise exceptions.AccessDenied(response_payload)
+            elif response.status_code == 404:
+                raise exceptions.ObjectNotFound(response_payload)
             elif response.status_code == 405:
                 raise exceptions.MethodNotAllowed(response_payload)
             return response_payload

diff --git a/docs/api/common.html b/docs/api/common.html
@@ -36,28 +36,32 @@ <h1 class="title">Module <code>push_to_3yourmind.api.common</code></h1>
 
 
 class CommonAPI(BaseAPI):
+    &#34;&#34;&#34;
+    API methods common to all panels.
+
+    Accessible via namespace `common`, for example:
+    &gt;&gt;&gt; response = client.common.get_colors()
+    &#34;&#34;&#34;
+
     def get_colors(self) -&gt; t.List[types.ResponseDict]:
         return self._request(&#34;GET&#34;, &#34;colors/&#34;)
 
     def get_units(self) -&gt; t.List[types.ResponseDict]:
         &#34;&#34;&#34;
         Get list of units of measure available on the platform.
         Currently, &#34;mm&#34; and &#34;inch&#34;.
-        :return:
         &#34;&#34;&#34;
         return self._request(&#34;GET&#34;, &#34;units/&#34;)
 
     def get_countries(self) -&gt; t.List[types.ResponseDict]:
         &#34;&#34;&#34;
         Get list of countries with codes and full names
-        :return:
         &#34;&#34;&#34;
         return self._request(&#34;GET&#34;, &#34;countries/&#34;)
 
     def get_currencies(self) -&gt; t.List[str]:
         &#34;&#34;&#34;
         Get list of currencies available on the platform
-        :return:
         &#34;&#34;&#34;
         return self._request(&#34;GET&#34;, &#34;currencies/&#34;)
 
@@ -82,36 +86,49 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <span>(</span><span>access_token: str, base_url: str)</span>
 </code></dt>
 <dd>
-<div class="desc"><p>Base class for all namespaced API methods.</p>
-<p>:param access_token:
-:param base_url:</p></div>
+<div class="desc"><p>API methods common to all panels.</p>
+<p>Accessible via namespace <code>common</code>, for example:</p>
+<pre><code class="language-python-repl">&gt;&gt;&gt; response = client.common.get_colors()
+</code></pre>
+<h2 id="args">Args</h2>
+<dl>
+<dt><strong><code>access_token</code></strong></dt>
+<dd>to create a token, open <code>/admin/auth/user/</code>, and click
+"Create token" in the user list.</dd>
+<dt><strong><code>base_url</code></strong></dt>
+<dd>application URL, ex. <a href="https://app.3yourmind.com">https://app.3yourmind.com</a></dd>
+</dl></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">class CommonAPI(BaseAPI):
+    &#34;&#34;&#34;
+    API methods common to all panels.
+
+    Accessible via namespace `common`, for example:
+    &gt;&gt;&gt; response = client.common.get_colors()
+    &#34;&#34;&#34;
+
     def get_colors(self) -&gt; t.List[types.ResponseDict]:
         return self._request(&#34;GET&#34;, &#34;colors/&#34;)
 
     def get_units(self) -&gt; t.List[types.ResponseDict]:
         &#34;&#34;&#34;
         Get list of units of measure available on the platform.
         Currently, &#34;mm&#34; and &#34;inch&#34;.
-        :return:
         &#34;&#34;&#34;
         return self._request(&#34;GET&#34;, &#34;units/&#34;)
 
     def get_countries(self) -&gt; t.List[types.ResponseDict]:
         &#34;&#34;&#34;
         Get list of countries with codes and full names
-        :return:
         &#34;&#34;&#34;
         return self._request(&#34;GET&#34;, &#34;countries/&#34;)
 
     def get_currencies(self) -&gt; t.List[str]:
         &#34;&#34;&#34;
         Get list of currencies available on the platform
-        :return:
         &#34;&#34;&#34;
         return self._request(&#34;GET&#34;, &#34;currencies/&#34;)
 
@@ -145,8 +162,7 @@ <h3>Methods</h3>
 </code></dt>
 <dd>
 <div class="desc"><p>Get list of units of measure available on the platform.
-Currently, "mm" and "inch".
-:return:</p></div>
+Currently, "mm" and "inch".</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
@@ -155,7 +171,6 @@ <h3>Methods</h3>
     &#34;&#34;&#34;
     Get list of units of measure available on the platform.
     Currently, &#34;mm&#34; and &#34;inch&#34;.
-    :return:
     &#34;&#34;&#34;
     return self._request(&#34;GET&#34;, &#34;units/&#34;)</code></pre>
 </details>
@@ -164,16 +179,14 @@ <h3>Methods</h3>
 <span>def <span class="ident">get_countries</span></span>(<span>self) ‑> List[Dict[str, Any]]</span>
 </code></dt>
 <dd>
-<div class="desc"><p>Get list of countries with codes and full names
-:return:</p></div>
+<div class="desc"><p>Get list of countries with codes and full names</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">def get_countries(self) -&gt; t.List[types.ResponseDict]:
     &#34;&#34;&#34;
     Get list of countries with codes and full names
-    :return:
     &#34;&#34;&#34;
     return self._request(&#34;GET&#34;, &#34;countries/&#34;)</code></pre>
 </details>
@@ -182,16 +195,14 @@ <h3>Methods</h3>
 <span>def <span class="ident">get_currencies</span></span>(<span>self) ‑> List[str]</span>
 </code></dt>
 <dd>
-<div class="desc"><p>Get list of currencies available on the platform
-:return:</p></div>
+<div class="desc"><p>Get list of currencies available on the platform</p></div>
 <details class="source">
 <summary>
 <span>Expand source code</span>
 </summary>
 <pre><code class="python">def get_currencies(self) -&gt; t.List[str]:
     &#34;&#34;&#34;
     Get list of currencies available on the platform
-    :return:
     &#34;&#34;&#34;
     return self._request(&#34;GET&#34;, &#34;currencies/&#34;)</code></pre>
 </details>