Update and fix docs

parafoxia · Jul 25, 2021 · 2b73b5f · 2b73b5f
1 parent da3202e
commit 2b73b5f
Show file tree

Hide file tree

Showing 16 changed files with 494 additions and 383 deletions.
diff --git a/docs/api.rst b/docs/api.rst
diff --git a/docs/app/analytix.rst b/docs/app/analytix.rst
@@ -0,0 +1,24 @@
+.. currentmodule:: analytix
+
+Library reference - analytix
+############################
+
+Version info
+============
+
+.. data:: __version__
+
+    The currently installed analytix version, represented in the :pep:`440` format.
+
+Exceptions
+==========
+
+.. autoclass:: analytix.errors.AnalytixError
+
+.. autoclass:: analytix.errors.InvalidScopes
+
+.. autoclass:: analytix.errors.InvalidRequest
+
+.. autoclass:: analytix.errors.HTTPError
+
+.. autoclass:: analytix.errors.MissingOptionalComponents
diff --git a/docs/app/yt-analytics.rst b/docs/app/yt-analytics.rst
@@ -0,0 +1,10 @@
+.. currentmodule:: analytix
+
+Library reference - YouTube analytics
+#####################################
+
+.. autoclass:: analytix.YouTubeAnalytics
+    :members:
+
+.. autoclass:: analytix.youtube.analytics.api.YouTubeAnalyticsReport
+    :members:
diff --git a/docs/changelog.rst b/docs/changelog.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,16 +15,14 @@
 
 import analytix
 
-sys.path.insert(0, os.path.abspath("../analytix"))
+sys.path.insert(0, os.path.abspath("."))
 
 
 # -- Project information -----------------------------------------------------
 
 project = "analytix"
 copyright = "2021, Ethan Henderson"
 author = "Ethan Henderson"
-
-# The full version, including alpha/beta/rc tags
 release = analytix.__version__
 
 
@@ -38,6 +36,7 @@
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
+    "sphinx_rtd_dark_mode",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -53,16 +52,13 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
 html_theme = "sphinx_rtd_theme"
+dafault_dark_mode = True
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
-
-html_context = {
-    "css_files": [
-        "_static/theme_overrides.css",  # overrides for wide tables in RTD theme
-    ],
-}
+html_css_files = [
+    "theme_overrides.css",  # overrides for wide tables in RTD theme
+]
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,8 +1,5 @@
-.. analytix documentation master file, created by
-   sphinx-quickstart on Thu Jan 28 01:44:50 2021.
-
 analytix
-====================================
+########
 
 .. image:: https://img.shields.io/pypi/v/analytix.svg
    :alt: PyPI version
@@ -12,51 +9,77 @@ analytix
    :alt: PyPI pyversions
    :target: https://pypi.python.org/pypi/analytix/
 
+.. image:: https://img.shields.io/pypi/implementation/analytix
+   :alt: PyPI - Implementation
+   :target: https://pypi.python.org/pypi/analytix/
+
+.. image:: https://img.shields.io/pypi/status/analytix
+   :alt: PyPI - Status
+   :target: https://pypi.python.org/pypi/analytix/
+
+.. image:: https://img.shields.io/pypi/dm/analytix
+   :alt: PyPI - Downloads
+   :target: https://pypistats.org/packages/analytix
+
+.. image:: https://img.shields.io/maintenance/yes/2021
+   :alt: Maintenance
+   :target: https://github.com/parafoxia/analytix
+
+.. image:: https://img.shields.io/github/release-date/parafoxia/analytix
+   :alt: GitHub Release Date
+   :target: https://github.com/parafoxia/analytix
+
+.. image:: https://img.shields.io/github/last-commit/parafoxia/analytix
+   :alt: GitHub last commit
+   :target: https://github.com/parafoxia/analytix
+
+.. image:: https://img.shields.io/readthedocs/analytix
+   :alt: Read the Docs
+   :target: https://analytix.readthedocs.io/en/latest/index.html
+
 .. image:: https://img.shields.io/github/license/parafoxia/analytix.svg
    :alt: License
    :target: https://github.com/parafoxia/analytix/blob/main/LICENSE
 
-A simple yet powerful API wrapper to make getting analytical information from the YouTube Analytics API easier than ever.
+A simple yet powerful API wrapper to make getting analytical information from your socials easier than ever.
+
+**Supported APIs**
+
+- YouTube Analytics API
 
 Features
---------
+========
 
 - Pythonic syntax lets you feel right at home
 - Dynamic error handling saves hours of troubleshooting, and makes sure only valid requests count toward your API quota
-- A clever interface allows you to make multiple requests per session without reauthorising
+- A clever interface allows you to make multiple requests across multiple sessions without reauthorising
 - Extra support allows the native saving of CSV files and conversion to DataFrame objects
 - Easy enough for beginners, but powerful enough for advanced users
 
-User Guide
-----------
-
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+   :caption: Quickstart
 
-   usage/install
-   usage/quickstart
-   usage/reports
-
-API Reference
--------------
+   starting/install
+   starting/first-report
 
 .. toctree::
-   :maxdepth: 2
-
-   api
+    :maxdepth: 1
+    :caption: Library reference
 
-Information
------------
+    app/analytix
+    app/yt-analytics
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
+    :caption: Guides and other references
 
-    changelog
+    refs/yt-analytics-setup
+    refs/yt-analytics-reports
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Information
 
-..  Indices and tables
-    ==================
-
-..  * :ref:`genindex`
-    * :ref:`modindex`
-    * :ref:`search`
+    info/changelog
+    info/migrating
diff --git a/docs/info/changelog.rst b/docs/info/changelog.rst
@@ -0,0 +1,4 @@
+Changelog
+#########
+
+For a full changelog, see the `releases page <https://github.com/parafoxia/analytix/releases>`_ on the GitHub repository.
diff --git a/docs/info/migrating.rst b/docs/info/migrating.rst
@@ -0,0 +1,22 @@
+Migrating to version 2
+######################
+
+This section will detail what changes you need to make to convert a project from using version 1 to version 2. Here are the things to keep in mind:
+
+- analytix now supports Python 3.6.
+- The number of dependencies has been reduced from 27 to 7. pandas is now an optional dependency, and so will need to be installed separately if you want it (you can use :code:`pip install "analytix[opt]"` to achieve the same effect).
+- The :class:`YouTubeService` class has been merged into the :class:`YouTubeAnalytics` class. Both authentication and retrieval are done through this new superclass.
+- The :class:`YouTubeAnalytics` class no longer needs to be manually authorised, though you can still do this if you want. This allows for verification to take place before needing to authorise.
+- Code authorisation is now the only authorisation method available.
+- The token returned by the YouTube Analytics API is now stored locally for future use. This token only lasts for an hour, but means you no longer need to authorise the client every time you restart the program. If you don't want analytix to store the token, you will need to manually authorise the client, making sure to pass :code:`store_token=False` to the authorisation method.
+- You are now required to pass a start date when retrieving reports.
+- You can no longer disable report verification.
+- Many verification entities (such as report type classes) now exist in different files. If you imported any of these features for whatever reason, you will need to check your import paths.
+- Any errors that previously raised :class:`Deprecated` now return :class:`InvalidRequest`.
+- Uncaught API errors now raise analytix's :class:`HTTPError` rather than google-api-python-client's :class:`HttpError`.
+- The :class:`NoAuthorisedService`, :class:`ServiceAlreadyExists`, and :class:`IncompleteRequest` errors now no longer exist.
+- You now need to access the number of rows and colums in a report via the :code:`shape` property rather than the :code:`nrows` and :code:`ncolumns` attributes respectively.
+- The :code:`type` attribute in the report class is now the friendly name of the report type rather than the instance itself.
+- When converting to a DataFrame, the "day" and "month" columns are now automatically converted to the datetime64[ns] dtype.
+
+This is not an exhaustive list of the changes and additions in version 2, but should provide an idea of what you need to change in your project. With that being said, a number of issues present in version 1 have been fixed in version 2. If you have been having problems with retrieving certain types of reports, it is recommended you migrate to version 2 and try again.