Handbook section with usage information

docs/_static/css/custom.css

@@ -17,6 +17,6 @@
  */
 
 .rst-content .toctree-wrapper:not(:last-child) ul {
-   margin-bottom: 0;
+   /*margin-bottom: 0;*/
    /* make adjacent toctrees appear to merge */
 }

docs/conf.py

@@ -32,11 +32,14 @@ version = '.'.join(release.split('.')[:3])
 # ones.
 extensions = [
     'myst_parser',
+    'sphinx_click',
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
 ]
 
+myst_heading_anchors = 2
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/handbook/commands.md

@@ -0,0 +1,7 @@
+# Command Reference
+
+```{eval-rst}
+.. click:: yaclog.cli.__main__:cli
+   :prog: yaclog
+   :nested: full
+```

docs/handbook/getting_started.md

@@ -0,0 +1,50 @@
+# Getting Started
+
+## Installation
+
+Install and update using [pip](https://pip.pypa.io/en/stable/quickstart/):
+
+```shell
+$ pip install -U yaclog
+```
+
+## Usage
+
+For detailed documentation on the {command}`yaclog` command and its subcommands see the {doc}`commands`.
+
+### Example workflow
+
+Create a new changelog in the current directory:
+```shell
+$ yaclog init
+```
+
+Add some new entries to the "Added" section of the current unreleased version:
+```shell
+$ yaclog entry -b 'Introduced some more bugs'
+$ yaclog entry -b 'Introduced some more features'
+```
+
+Show the current version:
+
+```shell
+$ yaclog show
+```
+```
+Unreleased
+
+- Introduced some more bugs
+- Introduced some more features
+```
+
+Release the current version and make a git tag for it
+
+```shell
+$ yaclog release --version 0.0.1 -c
+```
+```
+Renamed version "Unreleased" to "0.0.1".
+Commit and create tag for version 0.0.1? [y/N]: y
+Created commit a7b6789
+Created tag "0.0.1".
+```

docs/handbook/index.md

@@ -0,0 +1,11 @@
+# Handbook
+
+```{toctree}
+---
+maxdepth: 2
+glob:
+---
+
+getting_started
+commands
+```

docs/index.md

@@ -0,0 +1,30 @@
+# Yaclog: Yet Another Command Line Changelog Tool
+
+Yaclog is a python library and command line tool to make it easier to keep track of changes to your projects.
+It includes commands for appending new changes to a markdown changelog file, as well as releasing new versions
+for deployment via git tags.
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+---
+
+handbook/index
+reference/index
+```
+
+```{toctree}
+---
+maxdepth: 1
+---
+
+Changelog <changelog>
+License <license>
+```
+
+## Indices and tables
+
+* {ref}`genindex`
+* {ref}`modindex`
+* {ref}`search`

docs/index.rst

@@ -1,27 +0,0 @@
-Yaclog: Yet Another Command Line Changelog Tool
-===============================================
-
-Yaclog is a python library and command line tool to make it easier to keep track of changes to your projects.
-It includes commands for appending new changes to a markdown changelog file, as well as releasing new versions
-for deployment via git tags.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
-
-   API Reference <reference/index.rst>
-
-.. toctree::
-   :maxdepth: 1
-
-   Changelog <changelog>
-   License <license>
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`