restore classic docs

docs/.notes

@@ -0,0 +1,11 @@
+System Tests
+============
+
+The system tests use a real Google Account with its own Photos Library.
+
+This account is called gphotos.sync.test@gmail.com
+
+It's password uses giles' password scheme C 
+
+(I'd like this to be in public domain for use by other contributors but I 
+don't believe there is a secure way to do this.)

docs/_static/theme_overrides.css

@@ -0,0 +1,34 @@
+/* override table width restrictions */
+@media screen and (min-width: 639px) {
+    .wy-table-responsive table td {
+        /* !important prevents the common CSS stylesheets from
+           overriding this as on RTD they are loaded after this stylesheet */
+        white-space: normal !important;
+    }
+}
+
+/* override table padding */
+.rst-content table.docutils th, .rst-content table.docutils td {
+    padding: 4px 6px;
+}
+
+/* Add two-column option */
+@media only screen and (min-width: 1000px) {
+    .columns {
+        padding-left: 10px;
+        padding-right: 10px;
+        float: left;
+        width: 50%;
+        min-height: 145px;
+    }
+}
+
+.endcolumns {
+    clear: both
+}
+
+/* Hide toctrees within columns and captions from all toctrees.
+   This is what makes the include trick in index.rst work */
+.columns .toctree-wrapper, .toctree-wrapper .caption-text {
+    display: none;
+}

docs/conf.py

@@ -0,0 +1,120 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/main/usage/configuration.html
+
+import gphotos_sync
+
+# -- General configuration ------------------------------------------------
+
+# General information about the project.
+project = "gphotos-sync"
+
+# The full version, including alpha/beta/rc tags.
+release = gphotos_sync.__version__
+
+# The short X.Y version.
+if "+" in release:
+    # Not on a tag
+    version = "main"
+else:
+    version = release
+
+extensions = [
+    # Use this for generating API docs
+    "sphinx.ext.autodoc",
+    # This can parse google style docstrings
+    "sphinx.ext.napoleon",
+    # For linking to external sphinx documentation
+    "sphinx.ext.intersphinx",
+    # Add links to source code in API docs
+    "sphinx.ext.viewcode",
+    # Adds the inheritance-diagram generation directive
+    "sphinx.ext.inheritance_diagram",
+]
+
+# If true, Sphinx will warn about all references where the target cannot
+# be found.
+nitpicky = False
+
+# A list of (type, target) tuples (by default empty) that should be ignored when
+# generating warnings in "nitpicky mode". Note that type should include the
+# domain name if present. Example entries would be ('py:func', 'int') or
+# ('envvar', 'LD_LIBRARY_PATH').
+nitpick_ignore = [("py:func", "int", "py:class")]
+
+# Both the class’ and the __init__ method’s docstring are concatenated and
+# inserted into the main body of the autoclass directive
+autoclass_content = "both"
+
+# Order the members by the order they appear in the source code
+autodoc_member_order = "bysource"
+
+# Don't inherit docstrings from baseclasses
+autodoc_inherit_docstrings = False
+
+# Output graphviz directive produced images in a scalable format
+graphviz_output_format = "svg"
+
+# The name of a reST role (builtin or Sphinx extension) to use as the default
+# role, that is, for text marked up `like this`
+default_role = "any"
+
+# The suffix of source filenames.
+source_suffix = ".rst"
+
+# The main toctree document.
+main_doc = "index"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# These patterns also affect html_static_path and html_extra_path
+exclude_patterns = ["_build"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# This means you can link things like `str` and `asyncio` to the relevant
+# docs in the python documentation.
+intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
+
+# A dictionary of graphviz graph attributes for inheritance diagrams.
+inheritance_graph_attrs = {"rankdir": "TB"}
+
+# Common links that should be available on every page
+rst_epilog = """
+.. _Diamond Light Source:
+    http://www.diamond.ac.uk
+"""
+
+# Ignore localhost links for period check that links in docs are valid
+linkcheck_ignore = [r"http://localhost:\d+/"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme_github_versions"
+
+# Options for the sphinx rtd theme, use DLS blue
+html_theme_options = {"style_nav_header_background": "rgb(7, 43, 93)"}
+
+# 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"]
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+html_show_copyright = False
+
+# Add some CSS classes for columns and other tweaks in a custom css file
+html_css_files = ["theme_overrides.css"]
+
+# Logo
+html_logo = "images/logo.png"
+html_favicon = "images/logo.png"

docs/explanations.rst

@@ -0,0 +1,14 @@
+:orphan:
+
+Explanations
+============
+
+Explanation of how the library works and why it works that way.
+
+.. toctree::
+    :caption: Explanations
+
+    explanations/folders
+    explanations/notes
+    explanations/tokens
+    explanations/googleapiissues

docs/explanations/folders.rst

@@ -0,0 +1,43 @@
+.. _Folders:
+
+Folder Layout
+=============
+
+After doing a full sync you will have 2 directories off of the specified root:
+
+Media Files
+-----------
+
+photos:
+    contains all photos and videos from your Google Photos Library organized 
+    into folders with the structure 'photos/YYYY/MM' where 'YYYY/MM' is 
+    the date the photo/video was taken. The filenames within a folder will 
+    be as per the original upload except that duplicate names will have a 
+    suffix ' (n)' where n is the duplicate number of the file (this matches 
+    the approach used in the official Google tool for Windows).
+
+albums:
+    contains a folder hierarchy representing the set of albums and shared
+    albums in your library. All the files are symlinks to content in the photos
+    folder. The folder names will be 'albums/YYYY/MM Original Album Name'.
+
+Note that these are the default layouts and you can change what is downloaded
+and how it is layed out with command line options. See the help for details::
+
+    gphotos-sync --help
+
+Other Files
+-----------
+
+The following files will also appear in the root folder:-
+
+  - gphotos.sqlite: the database that tracks what files have been indexed,
+    you can open this with sqlite3 to examine what media and metadata you have.
+  - gphotos.log: a log of the most recent run, including debug info       
+  - gphotos.lock: the lock file used to make sure only one gphotos-sync runs
+    at a time   
+  - gphotos.trace: a trace file if logging is set to trace level. This logs 
+    the calls to the Google Photos API. 
+  - gphotos.bad_ids.yaml: A list of bad entries that cause the API to get 
+    an error when downloading. Delete this file to retry downloading these
+    bad items.

docs/explanations/googleapiissues.rst

@@ -0,0 +1,71 @@
+Known Issues
+============
+
+
+Known Issues with Google API
+----------------------------
+A few outstanding limitations of the Google API restrict what can be achieved. 
+All these issues have been reported to Google and this project will be updated 
+once they are resolved.
+
+Unfortunately, a number of quite significant issues have remained unfixed for 
+several years. I'm starting a discussion group in this repo for people to
+discuss workarounds, and collect reports of how these things are affecting 
+users. I intend to link this discussion group in the Google issue trackers
+to see if it will encourage some response from Google.
+
+To join the discussion go here 
+https://github.com/gilesknap/gphotos-sync/discussions.
+
+Pending API Issues
+~~~~~~~~~~~~~~~~~~
+
+-   There is no way to discover modified date of library media items. Currently 
+    ``gphotos-sync`` will refresh your local copy with any new photos added since 
+    the last scan but will not update any photos that have been modified in 
+    Google Photos.
+
+    - https://issuetracker.google.com/issues/122737849.
+
+
+-   GOOGLE WON'T FIX. The API strips GPS data from images.
+
+    - https://issuetracker.google.com/issues/80379228.
+
+-   Video download transcodes the videos even if you ask for the original file 
+    (=vd parameter). My experience is that the result is looks similar to the original
+    but the compression is more clearly visible. It is a smaller file with 
+    approximately 60% bitrate (same resolution).
+
+    - https://issuetracker.google.com/issues/80149160
+
+-   Photo download compresses the photos even if you ask for the original file 
+    (=d parameter). This is similar to the above issue, except in my experience 
+    is is nearly impossible to notice a loss in quality. It
+    is a file compressed to approximately 60% of the original size (same resolution).
+
+    - https://issuetracker.google.com/issues/112096115
+
+-   Burst shots are not supported. You will only see the first file of a burst shot.
+
+    - https://issuetracker.google.com/issues/124656564
+
+Fixed API Issues
+~~~~~~~~~~~~~~~~
+-   FIXED BY GOOGLE. Some types of video will not download using the new API.
+
+    - https://issuetracker.google.com/issues/116842164.
+    - https://issuetracker.google.com/issues/141255600
+
+Other Issues
+------------
+- Some mounted filesystems including NFS, CIFS and AFP do not support file locks 
+  and database access will fail on them.
+
+  - To fix, use the parameter --db-path to specify a location for your DB on 
+    the local disk. This will perform better anyway.
+
+GPS workaround
+--------------
+For a workaround to the GPS issue described below see this project  
+https://github.com/DennyWeinberg/manager-for-google-photos

docs/explanations/notes.rst

@@ -0,0 +1,17 @@
+Why is Google Photos Sync Read Only
+===================================
+
+Google Photos Sync is a backup tool only. It never makes any changes to your
+Google Photos Library in the cloud. There are two primary reasons for this:
+
+- The Photos API provided by Google is far too restricted to make changes 
+  in any meaningful way. For example
+
+  - there is no delete function
+  - you cannot add photos to an album unless it was created by the same
+    application that is trying to add photos
+
+- Even if the API allowed it, this would be a very hard problem, because
+  it is often hard to identify if a local photo or video matches one in the 
+  cloud. Besides this, I would not want the resposibility of potentially 
+  trashing someone's photo collection. 

docs/explanations/tokens.rst

@@ -0,0 +1,55 @@
+.. _Tokens:
+
+Google OAuth Tokens for gphotos-sync
+====================================
+
+Introduction
+------------
+
+There are two kinds of authentication required to run gphotos-sync.
+
+  - First the application must authenticate with Google to authorize the use
+    of the Google Photos API. This gives it permission to perform the 
+    second authentication step.
+  - Second, an individual User Account must me authenticated to allow access
+    to that user's Google Photos Library.
+
+The secret information that enables these authentication steps is held in 
+two files:
+
+  - client_secret.json holds the OAuth application ID that allows the 
+    first step. This is stored in an application configuration folder.
+    There is only one of these files per installation of gphotos-sync.
+    See `Client ID` for details of creating this file.
+  - .gphotos.token holds the user token for each user you are backing up 
+    photos for. This resides in the root folder of the library backup.
+    See `Login` for details of creating this file.
+
+Why Do We Need Client ID ?
+--------------------------
+
+The expected use of the client ID is that a vendor provides a single ID
+for their application, Google verifies the application and then anyone 
+can use it.
+
+In this scenario ALL Google API calls would count against the vendor's
+account. They would be charged for use of those APIs and they would
+need to charge their users to make this worthwhile.
+
+If I was to provide my own client ID with gphotos-sync then I would need
+to charge a subscription to cover API costs.
+
+Since this is FOSS I ask every user to create their own client ID
+so they can take advantage of the free tier of Google API use that is 
+available to every user.
+
+Most normal use of gphotos-sync does not exceed the free tier. If it does
+you will not be charged. The code is supposed to throttle back and go slower
+to drop back into the free usage rate. However there is an issue with this 
+feature at present and you will likely see an error:
+
+    ``429 Client Error: Too Many Requests for url``. 
+
+See https://github.com/gilesknap/gphotos-sync/issues/320,
+https://github.com/gilesknap/gphotos-sync/issues/202 for details and 
+workarounds.

docs/how-to.rst

@@ -0,0 +1,13 @@
+:orphan:
+
+How-to Guides
+=============
+
+Practical step-by-step guides for the more experienced user.
+
+.. toctree::
+    :caption: How-to Guides
+
+    how-to/windows
+    how-to/cron
+    how-to/comparison