Merge pull request #12 from crossjam/feature-automate-cli-documentati…

…on-generation-9

Automate cli documentation generation

.gitignore

@@ -9,3 +9,4 @@ venv
 .DS_Store
 *~
 /http_cache.sqlite
+/subcommands/http_cache.sqlite

README.md

@@ -6,7 +6,14 @@
 [![Tests](https://github.com/crossjam/feedbin-tools/workflows/Test/badge.svg)](https://github.com/crossjam/feedbin-tools/actions?query=workflow%3ATest)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/crossjam/feedbin-tools/blob/master/LICENSE)
 
-A command line toolkit for working with the [Feedbin HTTP API](https://github.com/feedbin/feedbin-api/)
+A command line toolkit for working with the [Feedbin HTTP
+API](https://github.com/feedbin/feedbin-api/)
+
+Right now we are focused on only reading (GET) from the Feedbin API
+for information retrieval, backup, collection, and analysis
+purposes. The cli is not intended to be a full fledged Feedbin
+client. If motivated, the mutating methods (PUT, POST) may be
+implemented in the future.
 
 ## Installation
 
@@ -26,15 +33,27 @@ You can also use:
 
     python -m feedbin_tools --help
 
+
+<!-- [[[cog
+import cog
+from feedbin_tools import cli
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli.cli, ["--help"])
+help = result.output.replace("Usage: cli", "Usage: feedbin-tools")
+cog.out(
+    "```\n{}\n```".format(help)
+)
+]]] -->
 ```
 Usage: feedbin-tools [OPTIONS] COMMAND [ARGS]...
 
   A command line toolkit for working with the Feedbin HTTP API
   https://github.com/feedbin/feedbin-api/
 
   Due to the use of the requests library for HTTP, .netrc is honored which is
-  another means of setting the HTTP Basic Auth user and password for the
-  feedbin endpoints
+  another means of setting the HTTP Basic Auth user and password for the feedbin
+  endpoints
 
 Options:
   --version          Show the version and exit.
@@ -48,9 +67,11 @@ Options:
 Commands:
   entries        Fetch entries for the authed feedbin user and emit as JSON
   feed           Fetch entries for feedbin feed FEED_ID and emit as JSON
-  starred        Fetch feedbin starred entries for the authed feedbin...
+  starred        Fetch feedbin starred entries for the authed feedbin user...
   subscriptions  Fetch feedbin subscriptions for the authed feedbin user...
+
 ```
+<!-- [[[end]]] -->
 
 ## Development
 
@@ -68,3 +89,6 @@ Now install the dependencies and test dependencies:
 To run the tests:
 
     pytest
+
+This is a hobby, side (very side) project. I’m grateful for PR
+submissions and filed issues, but responses might lag by quite a bit.

feedbin_tools/cli.py

@@ -149,7 +149,9 @@ def auth_from_context(ctx):
     return auth
 
 
-@cli.command(name="subscriptions")
+@cli.command(
+    name="subscriptions", short_help="Fetch feed subscriptions for feedbin user"
+)
 @click.option(
     "--since", type=click.STRING, default="", help="Return entries after this date"
 )
@@ -196,7 +198,7 @@ def subscriptions(ctx, since, extended):
         pass
 
 
-@cli.command(name="starred")
+@cli.command(name="starred", short_help="Fetch starred entries for feedbin user")
 @click.option("-b", "--chunk-size", type=click.INT, default=75)
 @click.option("--extended/--no-extended", default=False)
 @click.option("--ids/--no-ids", default=False)
@@ -265,7 +267,7 @@ def starred(ctx, chunk_size, extended, ids, limit):
                 total_emitted += 1
 
 
-@cli.command(name="feed")
+@cli.command(name="feed", short_help="Fetch feed entries for feedbin feed")
 @click.option("--extended/--no-extended", default=False)
 @click.option("--limit", type=click.INT, default=-1)
 @click.argument("feed_id")
@@ -298,7 +300,7 @@ def feed(ctx, feed_id, extended, limit):
         total_emitted += 1
 
 
-@cli.command(name="entries")
+@cli.command(name="entries", short_help="Fetch feed entries for feedbin user")
 @click.option("--read/--unread", default=False)
 @click.option("--starred/--no-starred", default=False)
 @click.option("--extended/--no-extended", default=False)

setup.cfg

@@ -21,11 +21,11 @@ install_requires =
 		 requests-cache
 		 stamina
 		 tenacity
-		 keyring
 
 [options.extras_require]
 test = pytest
        requests-mock
+       cogapp
 
 
 [options.entry_points]

subcommands/entries.md

@@ -0,0 +1,35 @@
+## Entries
+
+See the main [README.md](../README.md) for top level options for
+logging and authentication.
+
+<!-- [[[cog
+import cog
+from feedbin_tools import cli
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli.cli, ["entries", "--help"])
+help = result.output.replace("Usage: cli", "Usage: feedbin-tools")
+cog.out(
+    "```\n{}\n```".format(help)
+)
+]]] -->
+```
+Usage: feedbin-tools entries [OPTIONS]
+
+  Fetch entries for the authed feedbin user and emit as JSON
+
+Options:
+  --read / --unread
+  --starred / --no-starred
+  --extended / --no-extended
+  --limit INTEGER
+  -b, --per-page INTEGER
+  --since TEXT                    Return entries after this date
+  --include-original / --no-include-original
+  --include-enclosure / --no-include-enclosure
+  --include-content-diff / --no-include-content-diff
+  --help                          Show this message and exit.
+
+```
+<!-- [[[end]]] -->

subcommands/feed.md

@@ -0,0 +1,28 @@
+## Feed
+
+See the main [README.md](../README.md) for top level options for
+logging and authentication.
+
+<!-- [[[cog
+import cog
+from feedbin_tools import cli
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli.cli, ["feed", "--help"])
+help = result.output.replace("Usage: cli", "Usage: feedbin-tools")
+cog.out(
+    "```\n{}\n```".format(help)
+)
+]]] -->
+```
+Usage: feedbin-tools feed [OPTIONS] FEED_ID
+
+  Fetch entries for feedbin feed FEED_ID and emit as JSON
+
+Options:
+  --extended / --no-extended
+  --limit INTEGER
+  --help                      Show this message and exit.
+
+```
+<!-- [[[end]]] -->

subcommands/starred.md

@@ -0,0 +1,30 @@
+## Starred
+
+See the main [README.md](../README.md) for top level options for
+logging and authentication.
+
+<!-- [[[cog
+import cog
+from feedbin_tools import cli
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli.cli, ["starred", "--help"])
+help = result.output.replace("Usage: cli", "Usage: feedbin-tools")
+cog.out(
+    "```\n{}\n```".format(help)
+)
+]]] -->
+```
+Usage: feedbin-tools starred [OPTIONS]
+
+  Fetch feedbin starred entries for the authed feedbin user and emit as JSON
+
+Options:
+  -b, --chunk-size INTEGER
+  --extended / --no-extended
+  --ids / --no-ids
+  --limit INTEGER
+  --help                      Show this message and exit.
+
+```
+<!-- [[[end]]] -->

subcommands/subscriptions.md

@@ -0,0 +1,28 @@
+## Subscriptions
+
+See the main [README.md](../README.md) for top level options for
+logging and authentication.
+
+<!-- [[[cog
+import cog
+from feedbin_tools import cli
+from click.testing import CliRunner
+runner = CliRunner()
+result = runner.invoke(cli.cli, ["subscriptions", "--help"])
+help = result.output.replace("Usage: cli", "Usage: feedbin-tools")
+cog.out(
+    "```\n{}\n```".format(help)
+)
+]]] -->
+```
+Usage: feedbin-tools subscriptions [OPTIONS]
+
+  Fetch feedbin subscriptions for the authed feedbin user and emit as JSON
+
+Options:
+  --since TEXT                Return entries after this date
+  --extended / --no-extended  Include extended information
+  --help                      Show this message and exit.
+
+```
+<!-- [[[end]]] -->