Updated documentation

.gitignore

@@ -166,3 +166,5 @@ flake8-errors.txt
 RELEASE.txt
 site-packages
 reports
+temp.py
+todo.txt

cookie_composer/cli.py

@@ -8,7 +8,7 @@
 import rich_click as click
 
 from cookie_composer.commands.add import add_cmd
-from cookie_composer.commands.auth import auth_cli
+from cookie_composer.commands.authn import auth
 from cookie_composer.commands.create import create_cmd
 from cookie_composer.commands.link import link_cmd
 from cookie_composer.commands.update import update_cmd
@@ -24,7 +24,7 @@ def cli():
     pass
 
 
-cli.add_command(auth_cli, name="auth")
+cli.add_command(auth)
 
 
 @cli.command()

cookie_composer/commands/auth.py → cookie_composer/commands/authn.py

@@ -7,12 +7,12 @@
 
 
 @click.group()
-def auth_cli():
+def auth():
     """Authenticate cookie-composer to a service."""
     pass
 
 
-@auth_cli.command()
+@auth.command()
 @click.option(
     "-p",
     "--git-protocol",
@@ -61,7 +61,7 @@ def login(git_protocol: str, service: str, scopes: str, with_token: click.File):
 #     pass
 
 
-@auth_cli.command()
+@auth.command()
 @click.option(
     "-h",
     "--service",

cookie_composer/composition.py

@@ -46,7 +46,7 @@ class LayerConfig(BaseModel):
     """Directory within a git repository template that holds the cookiecutter.json file."""
 
     checkout: Optional[str]
-    """The branch, tag or commit to use if template is a git repository."""
+    """The branch, tag or commit to tell Cookie Cutter to use."""
 
     password: Optional[str]
     """The password to use if template is a password-protected Zip archive."""

docsrc/api.rst

@@ -10,8 +10,11 @@ API Reference
 
    ~commands
    ~merge_files
+   ~authentication
+   ~cc_overrides
    ~composition
    ~data_merge
+   ~diff
    ~exceptions
    ~git_commands
    ~layers

docsrc/how-to/access-private-templates.md

@@ -0,0 +1,50 @@
+# Accessing templates in private repositories
+
+Cookie composer can integrate with some third-party services in order to access private repositories.
+
+```{note}
+Currently only GitHub is supported.
+```
+
+## GitHub
+
+At your terminal, enter `cookie-composer auth login`:
+
+```console
+$ cookie-composer auth login
+First copy your one-time code: A25E-0A58
+Then visit https://github.com/login/device in your browser, and paste the code when prompted.
+Press Enter to open github.com in your browser...
+```
+
+Copy the one-time code (`A25E-0A58` in this example), and press Enter or Return to open your browser to the correct page.
+
+You will arrive at a page similar to this:
+
+![Activate the device](/_static/img/device-activation.png)
+
+Paste the code (or enter each character individually) and press the continue button.
+
+You will see an authorization page, similar to:
+
+![Authorize cookie-composer](/_static/img/authorize-composer.png)
+
+Press the "Authorize callowayproject" button to allow cookie-composer read-only access to your repositories.
+
+Then you will see:
+
+![All done!](/_static/img/authorize-done.png)
+
+And you can close the browser window.
+
+Your terminal will now look like:
+
+```console
+$ cookie-composer auth login
+First copy your one-time code: A25E-0A58
+Then visit https://github.com/login/device in your browser, and paste the code when prompted.
+Press Enter to open github.com in your browser...
+Waiting for authorization.............Authenticated to GitHub
+```
+
+Now when you provide any GitHub template link, Cookie Composer is able to access them as you with read-only access. 

docsrc/how-to/index.md

@@ -0,0 +1,8 @@
+# How To...
+
+```{toctree}
+---
+maxdepth: 2
+---
+access-private-templates
+```

docsrc/index.md

@@ -13,6 +13,7 @@ hidden:
 installation
 tutorial/index
 topic-guides/index
+how-to/index
 cli
 api
 contributing