fixing up docs

SMAPPNYU · Sep 12, 2018 · 8246901 · 8246901
1 parent f6eb1c3
commit 8246901
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 16 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,22 @@
+# Docs
+By: Leon Yin<br>
+Updated: 2018-09-12<br>
+
+Docs are generated using sphinx and hosted in read the docs. Please download all dependencies in the `requirements.txt` file to generate docs.
+
+the `conf.py` file is used to configure auto-generated API docs (via doc strings). It was created using `sphinx-quickstart`, this only really needs to be run once per project.
+
+The directions to auto-generate docs are made with this function:<br>
+```sphinx-apidoc -o source/ ../youtube_api/```
+
+This also only needs to be run once!
+
+Examples of how to use the code must be written in RST, stored in `source/usage/`, and referenced in the index.rst fil (see this [example](https://raw.githubusercontent.com/SMAPPNYU/youtube-data-api/master/docs/source/index.rst) for referencing usage/quickstart).
+
+To build docs just use the make file,`make html`. This will populate or re-populate the `build` directory.
+
+
+## Gotchas:
+Spacing and new lines are extremely important for RST!
+
+Read the docs's environment does not allow for C-packages. Many Python packages are optimized in Cython, we use mocking to fix this problem. When this is nto addressed the API docs are not properly generated on the read the docs site.
diff --git a/docs/source/requirements.txt → docs/requirements.txt b/docs/source/requirements.txt → docs/requirements.txt
diff --git a/docs/source/usage/quickstart.rst b/docs/source/usage/quickstart.rst
@@ -1,4 +1,3 @@
-
 Installation
 ------------
 
@@ -9,27 +8,28 @@ pip <https://pypi.org/project/youtube-data-api/>`__:
 
     pip install youtube-data-api
 
+
+.. _quickstart:
+
 Quickstart
 ----------
 
-.. code:: ipython3
+.. code:: python
 
     import os
     import pandas as pd
     from youtube_api import YoutubeDataApi
 
-In order to access the API, you'll need to get a `service key <https://developers.google.com/youtube/registering_an_application#Create_API_Keys>`_ from the `Google Cloud Console <https://console.cloud.google.com/>`_.
+In order to access the API, you'll need to get a `service key <https://developers.google.com/youtube/registering_an_application#Create_API_Keys>`_ from the `Google Cloud Console <https://console.cloud.google.com/>`_. I like to store my API keys as environment variables in ``~/.bash_profile`` so that I don't have to hard code them.:
 
-I like to store my API keys as environment variables in ``~/.bash_profile`` so that I don't have to hard code them:
+.. code:: python
 
-.. code:: ipython3
-
-    YT_KEY = os.environ.get('YT_KEY')
+    YT_KEY = os.environ.get('YOUTUBE_API_KEY') # you can hardcode this, too.
     yt = YoutubeDataApi(YT_KEY)
 
 We now have created a ``YoutubeDataAPi`` class as ``yt``, which can be used to make API calls, such as searching for the most relevant videos of Alexandra Ocasio-Cortez.
 
-.. code:: ipython3
+.. code:: python
 
     searches = yt.search(q='alexandria ocasio-cortez',
                          max_results=5)
@@ -58,7 +58,7 @@ All API requests are parsed from raw JSON into
 Typically an API call returns a list of OrderedDict objects. This is
 perfect for converting into Pandas DataFrames, or saving as JSON.
 
-.. code:: ipython3
+.. code:: python
 
     df_search = pd.DataFrame(searches)
     df_search
@@ -164,21 +164,16 @@ perfect for converting into Pandas DataFrames, or saving as JSON.
 
 
 
-The parsing step is a functional argument that users can customize so
-long as the only argument is dictionary.
-
-You can also get raw JSON from the API by using the ``raw_json`` parser,
-or setting parser to ``None``.
+Aside from the default parser, the ``parse`` argument allows users to create custom functions to parse and process API resonses. You can also get raw JSON from the API by using the :meth:`youtube_api.parsers.raw_json` parser, or setting parser to ``None``.
 
-.. code:: ipython3
+.. code:: python
 
     yt.search(q='alexandria ocasio-cortez', 
               max_results=1,
               parser=None)
 
 
 
-
 .. parsed-literal::
 
     [{'kind': 'youtube#searchResult',
@@ -200,3 +195,4 @@ or setting parser to ``None``.
        'channelTitle': 'VICE News',
        'liveBroadcastContent': 'none'}}]
 
+:mod:`youtube_api.parsers` are intended to allow customized data parsing for those who want it, with robust defaults for less advanced users.
diff --git a/docs/source/youtube_api.rst b/docs/source/youtube_api.rst
@@ -17,6 +17,7 @@ This is the client class to access the YouTube API.
 
 youtube_api.parsers module
 --------------------------
+Every function from the :mod:`youtube_api.youtube_api` class has an argument for ``parser``. ``parser`` can be any function that takes a dictionary as input. Here are the default parser fucntions for each function. Use these as templates to build your own custom parsers, or use the :meth:`youtube_api.parsers.raw_json` or ``None`` as the ``parser`` argument for the raw API response.
 
 .. automodule:: youtube_api.parsers
     :members: