Feature docs (#665)

* Added docs command

* Version bump

* Updated sphinx docs

MANIFEST.in

@@ -5,3 +5,4 @@ include osxphotos/queries/*
 include osxphotos/templates/*
 include README.md
 include README.rst
+include docs/

README.md

@@ -1804,7 +1804,7 @@ Substitution                    Description
 {lf}                            A line feed: '\n', alias for {newline}
 {cr}                            A carriage return: '\r'
 {crlf}                          a carriage return + line feed: '\r\n'
-{osxphotos_version}             The osxphotos version, e.g. '0.47.7'
+{osxphotos_version}             The osxphotos version, e.g. '0.47.8'
 {osxphotos_cmd_line}            The full command line used to run osxphotos
 
 The following substitutions may result in multiple values. Thus if specified
@@ -3717,7 +3717,7 @@ The following template field substitutions are availabe for use the templating s
 |{lf}|A line feed: '\n', alias for {newline}|
 |{cr}|A carriage return: '\r'|
 |{crlf}|a carriage return + line feed: '\r\n'|
-|{osxphotos_version}|The osxphotos version, e.g. '0.47.7'|
+|{osxphotos_version}|The osxphotos version, e.g. '0.47.8'|
 |{osxphotos_cmd_line}|The full command line used to run osxphotos|
 |{album}|Album(s) photo is contained in|
 |{folder_album}|Folder path + album photo is contained in. e.g. 'Folder/Subfolder/Album' or just 'Album' if no enclosing folder|

README.rst

@@ -86,32 +86,39 @@ Alternatively, you can also run the command line utility like this: ``python3 -m
 
    Options:
      --db <Photos database path>  Specify Photos database path. Path to Photos
-                                  library/database can be specified using either
+                                 library/database can be specified using either
-                                  --db or directly as PHOTOS_LIBRARY positional
+                                 --db or directly as PHOTOS_LIBRARY positional
-                                  argument. If neither --db or PHOTOS_LIBRARY
+                                 argument. If neither --db or PHOTOS_LIBRARY
-                                  provided, will attempt to find the library to
+                                 provided, will attempt to find the library to
-                                  use in the following order: 1. last opened
+                                 use in the following order: 1. last opened
-                                  library, 2. system library, 3.
+                                 library, 2. system library, 3.
-                                  ~/Pictures/Photos Library.photoslibrary
+                                 ~/Pictures/Photos Library.photoslibrary
-     --json                       Print output in JSON format.
+     --json                      Print output in JSON format.
      -v, --version                Show the version and exit.
      -h, --help                   Show this message and exit.
 
    Commands:
-     about     Print information about osxphotos including license.
+     about      Print information about osxphotos including license.
-     albums    Print out albums found in the Photos library.
+     albums     Print out albums found in the Photos library.
-     dump      Print list of all photos & associated info from the Photos...
+     diff       Compare two Photos databases and print out differences
-     export    Export photos from the Photos database.
+     dump       Print list of all photos & associated info from the Photos...
-     help      Print help; for help on commands: help <command>.
+     export     Export photos from the Photos database.
-     info      Print out descriptive info of the Photos library database.
+     help       Print help; for help on commands: help <command>.
-     keywords  Print out keywords found in the Photos library.
+     info       Print out descriptive info of the Photos library database.
-     labels    Print out image classification labels found in the Photos...
+     install    Install Python packages into the same environment as osxphotos
-     list      Print list of Photos libraries found on the system.
+     keywords   Print out keywords found in the Photos library.
-     persons   Print out persons (faces) found in the Photos library.
+     labels     Print out image classification labels found in the Photos...
-     places    Print out places found in the Photos library.
+     list       Print list of Photos libraries found on the system.
-     query     Query the Photos database using 1 or more search options; if...
+     persons    Print out persons (faces) found in the Photos library.
-     repl      Run interactive osxphotos shell
+     places     Print out places found in the Photos library.
-     tutorial  Display osxphotos tutorial.
+     query      Query the Photos database using 1 or more search options; if...
+     repl       Run interactive osxphotos REPL shell (useful for debugging,...
+     run        Run a python file using same environment as osxphotos
+     snap       Create snapshot of Photos database to use with diff command
+     theme      Manage osxphotos color themes.
+     tutorial   Display osxphotos tutorial.
+     uninstall  Uninstall Python packages from the osxphotos environment
+     uuid       Print out unique IDs (UUID) of photos selected in Photos
 
 To get help on a specific command, use ``osxphotos help <command_name>``
 

dev_requirements.txt

@@ -1,12 +1,13 @@
+Sphinx
 build
 m2r2
 pdbpp
 pyinstaller==4.10
 pytest-mock
 pytest==7.0.1
-Sphinx
 sphinx_click
 sphinx_rtd_theme
 sphinxcontrib-programoutput
+sphinxcontrib-programoutput
 twine
 wheel

docs/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 61bf98593db44b8d320314e5cbec33cf
+config: d1a90e805d591609a2d39f1deed3a0fe
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_modules/index.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Overview: module code &#8212; osxphotos 0.47.7 documentation</title>
+    <title>Overview: module code &#8212; osxphotos 0.47.8 documentation</title>
     <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="../_static/alabaster.css" />
     <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>

docs/_sources/cli.rst.txt

@@ -1,7 +1,7 @@
 osxphotos command line interface (CLI)
 ======================================
 
-.. click:: osxphotos.cli:cli
+.. click:: osxphotos.cli:cli_main
    :prog: osxphotos
    :nested: full
 

docs/_static/documentation_options.js

@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
     URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '0.47.7',
+    VERSION: '0.47.8',
     LANGUAGE: 'None',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

docs/index.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>Welcome to osxphotos’s documentation! &#8212; osxphotos 0.47.7 documentation</title>
+    <title>Welcome to osxphotos’s documentation! &#8212; osxphotos 0.47.8 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
@@ -99,32 +99,39 @@ Alternatively, you can also run the command line utility like this: <code class=
 
 <span class="n">Options</span><span class="p">:</span>
   <span class="o">--</span><span class="n">db</span> <span class="o">&lt;</span><span class="n">Photos</span> <span class="n">database</span> <span class="n">path</span><span class="o">&gt;</span>  <span class="n">Specify</span> <span class="n">Photos</span> <span class="n">database</span> <span class="n">path</span><span class="o">.</span> <span class="n">Path</span> <span class="n">to</span> <span class="n">Photos</span>
-                               <span class="n">library</span><span class="o">/</span><span class="n">database</span> <span class="n">can</span> <span class="n">be</span> <span class="n">specified</span> <span class="n">using</span> <span class="n">either</span>
+                              <span class="n">library</span><span class="o">/</span><span class="n">database</span> <span class="n">can</span> <span class="n">be</span> <span class="n">specified</span> <span class="n">using</span> <span class="n">either</span>
-                               <span class="o">--</span><span class="n">db</span> <span class="ow">or</span> <span class="n">directly</span> <span class="k">as</span> <span class="n">PHOTOS_LIBRARY</span> <span class="n">positional</span>
+                              <span class="o">--</span><span class="n">db</span> <span class="ow">or</span> <span class="n">directly</span> <span class="k">as</span> <span class="n">PHOTOS_LIBRARY</span> <span class="n">positional</span>
-                               <span class="n">argument</span><span class="o">.</span> <span class="n">If</span> <span class="n">neither</span> <span class="o">--</span><span class="n">db</span> <span class="ow">or</span> <span class="n">PHOTOS_LIBRARY</span>
+                              <span class="n">argument</span><span class="o">.</span> <span class="n">If</span> <span class="n">neither</span> <span class="o">--</span><span class="n">db</span> <span class="ow">or</span> <span class="n">PHOTOS_LIBRARY</span>
-                               <span class="n">provided</span><span class="p">,</span> <span class="n">will</span> <span class="n">attempt</span> <span class="n">to</span> <span class="n">find</span> <span class="n">the</span> <span class="n">library</span> <span class="n">to</span>
+                              <span class="n">provided</span><span class="p">,</span> <span class="n">will</span> <span class="n">attempt</span> <span class="n">to</span> <span class="n">find</span> <span class="n">the</span> <span class="n">library</span> <span class="n">to</span>
-                               <span class="n">use</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">following</span> <span class="n">order</span><span class="p">:</span> <span class="mf">1.</span> <span class="n">last</span> <span class="n">opened</span>
+                              <span class="n">use</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">following</span> <span class="n">order</span><span class="p">:</span> <span class="mf">1.</span> <span class="n">last</span> <span class="n">opened</span>
-                               <span class="n">library</span><span class="p">,</span> <span class="mf">2.</span> <span class="n">system</span> <span class="n">library</span><span class="p">,</span> <span class="mf">3.</span>
+                              <span class="n">library</span><span class="p">,</span> <span class="mf">2.</span> <span class="n">system</span> <span class="n">library</span><span class="p">,</span> <span class="mf">3.</span>
-                               <span class="o">~/</span><span class="n">Pictures</span><span class="o">/</span><span class="n">Photos</span> <span class="n">Library</span><span class="o">.</span><span class="n">photoslibrary</span>
+                              <span class="o">~/</span><span class="n">Pictures</span><span class="o">/</span><span class="n">Photos</span> <span class="n">Library</span><span class="o">.</span><span class="n">photoslibrary</span>
-  <span class="o">--</span><span class="n">json</span>                       <span class="n">Print</span> <span class="n">output</span> <span class="ow">in</span> <span class="n">JSON</span> <span class="nb">format</span><span class="o">.</span>
+  <span class="o">--</span><span class="n">json</span>                      <span class="n">Print</span> <span class="n">output</span> <span class="ow">in</span> <span class="n">JSON</span> <span class="nb">format</span><span class="o">.</span>
   <span class="o">-</span><span class="n">v</span><span class="p">,</span> <span class="o">--</span><span class="n">version</span>                <span class="n">Show</span> <span class="n">the</span> <span class="n">version</span> <span class="ow">and</span> <span class="n">exit</span><span class="o">.</span>
   <span class="o">-</span><span class="n">h</span><span class="p">,</span> <span class="o">--</span><span class="n">help</span>                   <span class="n">Show</span> <span class="n">this</span> <span class="n">message</span> <span class="ow">and</span> <span class="n">exit</span><span class="o">.</span>
 
 <span class="n">Commands</span><span class="p">:</span>
-  <span class="n">about</span>     <span class="n">Print</span> <span class="n">information</span> <span class="n">about</span> <span class="n">osxphotos</span> <span class="n">including</span> <span class="n">license</span><span class="o">.</span>
+  <span class="n">about</span>      <span class="n">Print</span> <span class="n">information</span> <span class="n">about</span> <span class="n">osxphotos</span> <span class="n">including</span> <span class="n">license</span><span class="o">.</span>
-  <span class="n">albums</span>    <span class="n">Print</span> <span class="n">out</span> <span class="n">albums</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
+  <span class="n">albums</span>     <span class="n">Print</span> <span class="n">out</span> <span class="n">albums</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
-  <span class="n">dump</span>      <span class="n">Print</span> <span class="nb">list</span> <span class="n">of</span> <span class="nb">all</span> <span class="n">photos</span> <span class="o">&amp;</span> <span class="n">associated</span> <span class="n">info</span> <span class="kn">from</span> <span class="nn">the</span> <span class="n">Photos</span><span class="o">...</span>
+  <span class="n">diff</span>       <span class="n">Compare</span> <span class="n">two</span> <span class="n">Photos</span> <span class="n">databases</span> <span class="ow">and</span> <span class="nb">print</span> <span class="n">out</span> <span class="n">differences</span>
-  <span class="n">export</span>    <span class="n">Export</span> <span class="n">photos</span> <span class="kn">from</span> <span class="nn">the</span> <span class="n">Photos</span> <span class="n">database</span><span class="o">.</span>
+  <span class="n">dump</span>       <span class="n">Print</span> <span class="nb">list</span> <span class="n">of</span> <span class="nb">all</span> <span class="n">photos</span> <span class="o">&amp;</span> <span class="n">associated</span> <span class="n">info</span> <span class="kn">from</span> <span class="nn">the</span> <span class="n">Photos</span><span class="o">...</span>
-  <span class="n">help</span>      <span class="n">Print</span> <span class="n">help</span><span class="p">;</span> <span class="k">for</span> <span class="n">help</span> <span class="n">on</span> <span class="n">commands</span><span class="p">:</span> <span class="n">help</span> <span class="o">&lt;</span><span class="n">command</span><span class="o">&gt;.</span>
+  <span class="n">export</span>     <span class="n">Export</span> <span class="n">photos</span> <span class="kn">from</span> <span class="nn">the</span> <span class="n">Photos</span> <span class="n">database</span><span class="o">.</span>
-  <span class="n">info</span>      <span class="n">Print</span> <span class="n">out</span> <span class="n">descriptive</span> <span class="n">info</span> <span class="n">of</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span> <span class="n">database</span><span class="o">.</span>
+  <span class="n">help</span>       <span class="n">Print</span> <span class="n">help</span><span class="p">;</span> <span class="k">for</span> <span class="n">help</span> <span class="n">on</span> <span class="n">commands</span><span class="p">:</span> <span class="n">help</span> <span class="o">&lt;</span><span class="n">command</span><span class="o">&gt;.</span>
-  <span class="n">keywords</span>  <span class="n">Print</span> <span class="n">out</span> <span class="n">keywords</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
+  <span class="n">info</span>       <span class="n">Print</span> <span class="n">out</span> <span class="n">descriptive</span> <span class="n">info</span> <span class="n">of</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span> <span class="n">database</span><span class="o">.</span>
-  <span class="n">labels</span>    <span class="n">Print</span> <span class="n">out</span> <span class="n">image</span> <span class="n">classification</span> <span class="n">labels</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span><span class="o">...</span>
+  <span class="n">install</span>    <span class="n">Install</span> <span class="n">Python</span> <span class="n">packages</span> <span class="n">into</span> <span class="n">the</span> <span class="n">same</span> <span class="n">environment</span> <span class="k">as</span> <span class="n">osxphotos</span>
-  <span class="nb">list</span>      <span class="n">Print</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">Photos</span> <span class="n">libraries</span> <span class="n">found</span> <span class="n">on</span> <span class="n">the</span> <span class="n">system</span><span class="o">.</span>
+  <span class="n">keywords</span>   <span class="n">Print</span> <span class="n">out</span> <span class="n">keywords</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
-  <span class="n">persons</span>   <span class="n">Print</span> <span class="n">out</span> <span class="n">persons</span> <span class="p">(</span><span class="n">faces</span><span class="p">)</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
+  <span class="n">labels</span>     <span class="n">Print</span> <span class="n">out</span> <span class="n">image</span> <span class="n">classification</span> <span class="n">labels</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span><span class="o">...</span>
-  <span class="n">places</span>    <span class="n">Print</span> <span class="n">out</span> <span class="n">places</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
+  <span class="nb">list</span>       <span class="n">Print</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">Photos</span> <span class="n">libraries</span> <span class="n">found</span> <span class="n">on</span> <span class="n">the</span> <span class="n">system</span><span class="o">.</span>
-  <span class="n">query</span>     <span class="n">Query</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">database</span> <span class="n">using</span> <span class="mi">1</span> <span class="ow">or</span> <span class="n">more</span> <span class="n">search</span> <span class="n">options</span><span class="p">;</span> <span class="k">if</span><span class="o">...</span>
+  <span class="n">persons</span>    <span class="n">Print</span> <span class="n">out</span> <span class="n">persons</span> <span class="p">(</span><span class="n">faces</span><span class="p">)</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
-  <span class="n">repl</span>      <span class="n">Run</span> <span class="n">interactive</span> <span class="n">osxphotos</span> <span class="n">shell</span>
+  <span class="n">places</span>     <span class="n">Print</span> <span class="n">out</span> <span class="n">places</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">library</span><span class="o">.</span>
-  <span class="n">tutorial</span>  <span class="n">Display</span> <span class="n">osxphotos</span> <span class="n">tutorial</span><span class="o">.</span>
+  <span class="n">query</span>      <span class="n">Query</span> <span class="n">the</span> <span class="n">Photos</span> <span class="n">database</span> <span class="n">using</span> <span class="mi">1</span> <span class="ow">or</span> <span class="n">more</span> <span class="n">search</span> <span class="n">options</span><span class="p">;</span> <span class="k">if</span><span class="o">...</span>
+  <span class="n">repl</span>       <span class="n">Run</span> <span class="n">interactive</span> <span class="n">osxphotos</span> <span class="n">REPL</span> <span class="n">shell</span> <span class="p">(</span><span class="n">useful</span> <span class="k">for</span> <span class="n">debugging</span><span class="p">,</span><span class="o">...</span>
+  <span class="n">run</span>        <span class="n">Run</span> <span class="n">a</span> <span class="n">python</span> <span class="n">file</span> <span class="n">using</span> <span class="n">same</span> <span class="n">environment</span> <span class="k">as</span> <span class="n">osxphotos</span>
+  <span class="n">snap</span>       <span class="n">Create</span> <span class="n">snapshot</span> <span class="n">of</span> <span class="n">Photos</span> <span class="n">database</span> <span class="n">to</span> <span class="n">use</span> <span class="k">with</span> <span class="n">diff</span> <span class="n">command</span>
+  <span class="n">theme</span>      <span class="n">Manage</span> <span class="n">osxphotos</span> <span class="n">color</span> <span class="n">themes</span><span class="o">.</span>
+  <span class="n">tutorial</span>   <span class="n">Display</span> <span class="n">osxphotos</span> <span class="n">tutorial</span><span class="o">.</span>
+  <span class="n">uninstall</span>  <span class="n">Uninstall</span> <span class="n">Python</span> <span class="n">packages</span> <span class="kn">from</span> <span class="nn">the</span> <span class="n">osxphotos</span> <span class="n">environment</span>
+  <span class="n">uuid</span>       <span class="n">Print</span> <span class="n">out</span> <span class="n">unique</span> <span class="n">IDs</span> <span class="p">(</span><span class="n">UUID</span><span class="p">)</span> <span class="n">of</span> <span class="n">photos</span> <span class="n">selected</span> <span class="ow">in</span> <span class="n">Photos</span>
 </pre></div>
 </div>
 <p>To get help on a specific command, use <code class="docutils literal notranslate"><span class="pre">osxphotos</span> <span class="pre">help</span> <span class="pre">&lt;command_name&gt;</span></code></p>
@@ -281,7 +288,33 @@ Alternatively, you can also run the command line utility like this: <code class=
 <p>Reference full documentation on <a class="reference external" href="https://github.com/RhetTbull/osxphotos/blob/master/README.md">GitHub</a></p>
 <div class="toctree-wrapper compound">
 <ul>
-<li class="toctree-l1"><a class="reference internal" href="cli.html">osxphotos command line interface (CLI)</a></li>
+<li class="toctree-l1"><a class="reference internal" href="cli.html">osxphotos command line interface (CLI)</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="cli.html#osxphotos">osxphotos</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-about">about</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-albums">albums</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-diff">diff</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-dump">dump</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-export">export</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-help">help</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-info">info</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-install">install</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-keywords">keywords</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-labels">labels</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-list">list</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-persons">persons</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-places">places</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-query">query</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-repl">repl</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-run">run</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-snap">snap</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-theme">theme</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-tutorial">tutorial</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-uninstall">uninstall</a></li>
+<li class="toctree-l3"><a class="reference internal" href="cli.html#osxphotos-uuid">uuid</a></li>
+</ul>
+</li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="reference.html">osxphotos package</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="reference.html#osxphotos-module">osxphotos module</a></li>
 </ul>

docs/modules.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>osxphotos &#8212; osxphotos 0.47.7 documentation</title>
+    <title>osxphotos &#8212; osxphotos 0.47.8 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>

docs/reference.html

@@ -6,7 +6,7 @@
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
 
-    <title>osxphotos package &#8212; osxphotos 0.47.7 documentation</title>
+    <title>osxphotos package &#8212; osxphotos 0.47.8 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>

docs/search.html

@@ -5,7 +5,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Search &#8212; osxphotos 0.47.7 documentation</title>
+    <title>Search &#8212; osxphotos 0.47.8 documentation</title>
     <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
     <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
     

docsrc/source/cli.rst

@@ -1,7 +1,7 @@
 osxphotos command line interface (CLI)
 ======================================
 
-.. click:: osxphotos.cli:cli
+.. click:: osxphotos.cli:cli_main
    :prog: osxphotos
    :nested: full
 

docsrc/source/conf.py

@@ -30,9 +30,7 @@ about = {}
 this_directory = pathlib.Path(__file__).parent
 version_file = this_directory.parent.parent / "osxphotos" / "_version.py"
 # get version info from _version
-with open(
+with open(version_file, mode="r", encoding="utf-8") as f:
-   version_file, mode="r", encoding="utf-8"
-) as f:
     exec(f.read(), about)
 
 # The full version, including alpha/beta/rc tags
@@ -44,7 +42,15 @@ release = about["__version__"]
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx_click", "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", "m2r2"] 
+extensions = [
+    "sphinx_click",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "m2r2",
+    "sphinxcontrib.programoutput",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -66,4 +72,3 @@ html_theme = "alabaster"
 # 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"]
-

osxphotos/_version.py

@@ -1,3 +1,3 @@
 """ version info """
 
-__version__ = "0.47.7"
+__version__ = "0.47.8"

osxphotos/cli/cli.py

@@ -9,6 +9,7 @@ from .about import about
 from .albums import albums
 from .common import DB_OPTION, JSON_OPTION, OSXPHOTOS_HIDDEN
 from .debug_dump import debug_dump
+from .docs import docs
 from .dump import dump
 from .export import export
 from .exportdb import exportdb
@@ -62,6 +63,7 @@ for command in [
     albums,
     debug_dump,
     diff,
+    docs,
     dump,
     export,
     exportdb,

osxphotos/cli/docs.py

@@ -0,0 +1,63 @@
+"""docs command for osxphotos CLI """
+
+import pathlib
+import shutil
+from typing import Optional
+
+import click
+
+from osxphotos._version import __version__
+
+from .common import get_config_dir
+
+
+@click.command(hidden=True)
+@click.pass_obj
+@click.pass_context
+def docs(ctx, cli_obj):
+    """Open osxphotos documentation in your browser."""
+
+    docs_dir = get_config_dir() / "docs"
+    if not docs_dir.exists():
+        docs_dir.mkdir(parents=True)
+
+    docs_version = get_docs_version(docs_dir)
+    if not docs_version or docs_version != __version__:
+        click.echo(f"Copying docs for osxphotos version {__version__}")
+        shutil.rmtree(str(docs_dir), ignore_errors=True)
+        copy_docs(docs_dir)
+        set_docs_version(docs_dir, __version__)
+
+    index = docs_dir / "index.html"
+    click.echo(f"Opening {index}")
+    click.launch(str(index))
+
+
+def get_docs_version(docs_dir: pathlib.Path) -> Optional[str]:
+    """Get the version of the docs directory"""
+
+    if not docs_dir.exists():
+        return None
+
+    version_file = docs_dir / ".version"
+    if not version_file.exists():
+        return None
+
+    with version_file.open() as f:
+        return f.read().strip()
+
+
+def copy_docs(docs_dir: pathlib.Path):
+    """Copy the latest docs to the docs directory"""
+    # there must be a better way to do this
+    src_dir = pathlib.Path(__file__).parent.parent.parent / "docs"
+    shutil.copytree(str(src_dir), str(docs_dir))
+
+
+def set_docs_version(docs_dir: pathlib.Path, version: str):
+    """Set the version of the docs directory"""
+    version_file = docs_dir / ".version"
+    if version_file.exists():
+        version_file.unlink()
+    with version_file.open("w") as f:
+        f.write(version)