switch the docs Sphinx theme from alabaster to RTD

https://sphinx-rtd-theme.readthedocs.io/

README.md

@@ -32,23 +32,18 @@ Granary is a library and REST API that fetches and converts between a wide varie
 Here's how to get started:
 
 * Granary is [available on PyPi.](https://pypi.python.org/pypi/granary/) Install with `pip install granary`.
-* [Click here for getting started docs.](#using)
-* [Click here for reference docs.](https://granary.readthedocs.io/en/latest/source/granary.html)
-* The REST API and demo app are deployed at [granary.io](https://granary.io/).
-
-[Versions 3.0](https://pypi.org/project/oauth-dropins/2.2/) and above support App Engine's [Python 3 runtimes](https://cloud.google.com/appengine/docs/python/), both [Standard](https://cloud.google.com/appengine/docs/standard/python3/) and [Flexible](https://cloud.google.com/appengine/docs/flexible/python/). If you're on the [Python 2 runtime](https://cloud.google.com/appengine/docs/standard/python/), use [version 2.2](https://pypi.org/project/oauth-dropins/2.2/).
+* [Getting started docs.](#using)
+* [Reference docs.](https://granary.readthedocs.io/en/latest/source/granary.html)
+* REST API and demo app at [granary.io](https://granary.io/).
+* [Source code on GitHub.](https://github.com/snarfed/granary/)
 
 License: This project is placed in the public domain.
 
 
 Using
 ---
 
-All dependencies are handled by pip and enumerated in [requirements.txt](https://github.com/snarfed/granary/blob/master/requirements.txt). We recommend that you install with pip in a [`virtualenv`](http://docs.python-guide.org/en/latest/dev/virtualenvs/). ([App Engine details.](https://cloud.google.com/appengine/docs/python/tools/libraries27#vendoring))
-
-The library and REST API are both based on the [OpenSocial Activity Streams service](https://opensocial.github.io/spec/2.0.1/Social-API-Server.xml#ActivityStreams-Service).
-
-Let's start with an example. This code using the library:
+The library and REST API are both based on the [OpenSocial Activity Streams service](https://opensocial.github.io/spec/2.0.1/Social-API-Server.xml#ActivityStreams-Service). Let's start with an example. This code using the library:
 
 ```python
 from granary import twitter

docs/_static/custom.css

@@ -0,0 +1,23 @@
+/* Duplicated in oauth-dropins and bridgy! */
+.icon-home {
+  font-size: larger !important;
+}
+
+.wy-nav-side, .wy-side-nav-search > div.version {
+  color:#fcfcfc;
+}
+
+.rst-content code, .rst-content tt, code {
+  border: none;
+  padding: 0;
+}
+
+/* The first link in the reference doc TOC is the page title/header. Hide that.  */
+#contents #id1 {
+  display: none;
+}
+
+/* The first link in the sidebar TOC is the page title/header. Hide that.  */
+.local-toc ul:nth-child(3) li:first-child {
+  display: none;
+}

docs/_templates/breadcrumbs.html

@@ -0,0 +1 @@
+<hr/>

docs/_templates/layout.html

@@ -0,0 +1,34 @@
+{% extends "!layout.html" %}
+
+{%- block navigation %}
+
+
+<div style="width: 300px; text-align: center; font-size: larger">
+
+<p>The social web translator</p>
+
+<!---
+<p>
+<a href="https://circleci.com/gh/snarfed/granary">
+  <img alt="Tests on Circle CI" src="https://circleci.com/gh/snarfed/granary.svg?style=svg" />
+</a>
+<a href="https://coveralls.io/github/snarfed/granary?branch=master">
+  <img alt="Coverage on Coveralls" src="https://coveralls.io/repos/github/snarfed/granary/badge.svg?branch=master" />
+</a>
+</p>
+-->
+</div>
+
+<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="{{ _('Navigation menu') }}">
+<div class="local-toc">
+  <ul>
+    <li><a href="{{ pathto('index') }}">Getting started</a></li>
+    <li><a href="{{ pathto('source/granary') }}">Reference documentation</a></li>
+  </ul>
+  <hr style="margin: 1em">
+  {{ toc }}
+</div>
+</div>
+
+
+{%- endblock %}

docs/build.sh

@@ -19,11 +19,11 @@ cd `dirname $absfile`
 rm -f index.rst
 cat > index.rst <<EOF
 granary
-=======
+-------
 
 EOF
 
-tail -n +19 ../README.md \
+tail -n +21 ../README.md \
   | pandoc --from=markdown --to=rst \
   | sed -E 's/```/`/; s/`` </ </' \
   >> index.rst

docs/conf.py

@@ -13,6 +13,7 @@
 
 import sys
 import os
+import sphinx_rtd_theme
 
 # 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
@@ -37,6 +38,7 @@
     'sphinx.ext.intersphinx',
     # 'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinx_rtd_theme',
 ]
 
 # autodoc settings
@@ -77,7 +79,7 @@
 
 # General information about the project.
 project = 'granary'
-copyright = '2012-2020, Ryan Barrett'
+copyright = '2012-2022, Ryan Barrett'
 author = 'Ryan Barrett'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -142,12 +144,15 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+# https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
+html_theme_options = {
+    'collapse_navigation': False,
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -161,7 +166,7 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = '../static/granary_logo_512.png'
+html_logo = '../static/granary_logo_128.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -171,7 +176,7 @@
 # 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 = []
+html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -187,9 +192,16 @@
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-html_sidebars = {
-  '**': ['description.html', 'localtoc.html', 'searchbox.html'],
-}
+# html_sidebars = {
+#   '**': ['description.html', 'localtoc.html', 'searchbox.html'],
+# }
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+# https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html
+html_css_files = [
+    'custom.css',
+]
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/index.rst

@@ -1,7 +1,5 @@
 granary
-=======
-
---------------
+-------
 
 Granary is a library and REST API that fetches and converts between a
 wide variety of data sources and formats:
@@ -26,38 +24,20 @@ Here’s how to get started:
 -  Granary is `available on
    PyPi. <https://pypi.python.org/pypi/granary/>`__ Install with
    ``pip install granary``.
--  `Click here for getting started docs. <#using>`__
--  `Click here for reference
+-  `Getting started docs. <#using>`__
+-  `Reference
    docs. <https://granary.readthedocs.io/en/latest/source/granary.html>`__
--  The REST API and demo app are deployed at
-   `granary.io <https://granary.io/>`__.
-
-`Versions 3.0 <https://pypi.org/project/oauth-dropins/2.2/>`__ and above
-support App Engine’s `Python 3
-runtimes <https://cloud.google.com/appengine/docs/python/>`__, both
-`Standard <https://cloud.google.com/appengine/docs/standard/python3/>`__
-and
-`Flexible <https://cloud.google.com/appengine/docs/flexible/python/>`__.
-If you’re on the `Python 2
-runtime <https://cloud.google.com/appengine/docs/standard/python/>`__,
-use `version 2.2 <https://pypi.org/project/oauth-dropins/2.2/>`__.
+-  REST API and demo app at `granary.io <https://granary.io/>`__.
+-  `Source code on GitHub. <https://github.com/snarfed/granary/>`__
 
 License: This project is placed in the public domain.
 
 Using
 -----
 
-All dependencies are handled by pip and enumerated in
-`requirements.txt <https://github.com/snarfed/granary/blob/master/requirements.txt>`__.
-We recommend that you install with pip in a
-`virtualenv <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`__.
-(`App Engine
-details. <https://cloud.google.com/appengine/docs/python/tools/libraries27#vendoring>`__)
-
 The library and REST API are both based on the `OpenSocial Activity
 Streams
 service <https://opensocial.github.io/spec/2.0.1/Social-API-Server.xml#ActivityStreams-Service>`__.
-
 Let’s start with an example. This code using the library:
 
 .. code:: python
@@ -176,22 +156,15 @@ the source data. (Instagram responses are cached for 60m.) You can
 prevent this by adding the ``cache=false`` query parameter to your
 request.
 
+Include the ``shares=false`` query parameter to omit shares, eg Twitter
+retweets, from the results.
+
 To use the REST API in an existing ActivityStreams client, you’ll need
 to hard-code exceptions for the domains you want to use
 e.g. ``facebook.com``, and redirect HTTP requests to the corresponding
 `endpoint above <#about>`__.
 
-Instagram is disabled in the REST API entirely, sadly, `due to their
-aggressive rate limiting and
-blocking <https://github.com/snarfed/bridgy/issues/665#issuecomment-524977427>`__.
-
-The web UI (`granary.io <https://granary.io/>`__) currently only fetches
-Facebook access tokens for users. If you want to use it to access a
-Facebook page, you’ll need to get an access token manually with the
-`Graph API Explorer <https://developers.facebook.com/tools/explorer/>`__
-(click on the *Get To…* drop-down) . Then, log into Facebook on
-`granary.io <https://granary.io/>`__ and paste the page access token
-into the ``access_token`` text box.
+Facebook and Instagram are disabled in the REST API entirely, sadly.
 
 Using the library
 -----------------
@@ -491,14 +464,26 @@ Changelog
 
 -  Drop Python 3.5 support. Python 3.6 is now the minimum required
    version.
--  Instagram:
+-  Add new ``include_shares`` kwarg to ``get_activities``, implemented
+   for Twitter and Mastodon. Defaults to ``True``. If ``False``, shares
+   (retweets in Twitter, boosts in Mastodon) will be discarded and not
+   returned. Also add a corresponding ``shares`` query param to the REST
+   API.
+-  Instagram (scraping):
 
-   -  Scraping: handle media items with no ``user`` object.
+   -  Handle media items with no ``user`` object, add new fetch for
+      comments.
+   -  Add ``Instagram.merge_scraped_comments()``.
 
--  AS2:
+-  ActivityStreams 2:
 
    -  Handle error when ``type`` isn’t a string.
 
+-  Reddit:
+
+   -  Implement ``get_activities()`` to fetch posts by the current user
+      or a user specified with ``user_id``.
+
 3.2 - 2021-09-15
 ~~~~~~~~~~~~~~~~
 

docs/requirements.txt

@@ -1 +1,2 @@
 sphinx~=4.4
+sphinx-rtd-theme>=1.0.0

docs/source/granary.rst

@@ -1,10 +1,9 @@
 granary package
-===============
+---------------
 
 Reference documentation.
 
-.. toctree::
-    granary
+.. contents::
 
 as2
 ---

granary/microformats2.py

@@ -1255,8 +1255,8 @@ def size_to_bytes(size):
   """Converts a string file size to an integer number of bytes.
 
   Args:
-    size, string, may be either integer bytes or human-readable approximation,
-      eg 7MB or 1.23 kb
+    size: string, may be either integer bytes or human-readable approximation,
+          eg 7MB or 1.23 kb
 
   Returns: integer, bytes, or None if size can't be parsed
   """