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`

yaclog/cli/__main__.py

@@ -72,7 +72,7 @@ def reformat(obj: Changelog):
 def show(obj: Changelog, all_versions, markdown, str_func, version_names):
     """Show the changes for VERSIONS.
 
-    VERSIONS is a list of versions to click.echo. If not given, the most recent version is used.
+    VERSIONS is a list of versions to print. If not given, the most recent version is used.
     """
 
     try:
@@ -97,7 +97,7 @@ def show(obj: Changelog, all_versions, markdown, str_func, version_names):
 
 @cli.command(short_help='Modify version tags')
 @click.option('--add/--delete', '-a/-d', default=True, is_flag=True, help='Add or delete tags')
-@click.argument('tag_name', metavar='tag', type=str)
+@click.argument('tag_name', metavar='TAG', type=str)
 @click.argument('version_name', metavar='VERSION', type=str, required=False)
 @click.pass_obj
 def tag(obj: Changelog, add, tag_name: str, version_name: str):

yaclog/version.py

@@ -1,5 +1,5 @@
 """
-Various helper functions for analyzing and manipulating PEP440 version numbers,
+Various helper functions for analyzing and manipulating :pep:`440` version numbers,
 meant to augment the `packaging.version` module.
 """
 
@@ -29,7 +29,7 @@ version_regex = re.compile(VERSION_PATTERN, re.VERBOSE | re.IGNORECASE)
 
 def extract_version(version_str: str) -> Tuple[Optional[Version], int, int]:
     """
-    Extracts a PEP440 version object from a string which may have other text
+    Extracts a :pep:`440` version object from a string which may have other text
 
     :param version_str: The input string to extract from
     :return: A tuple of (version, start, end), where start and end are the span of the version in the original string
@@ -42,7 +42,7 @@ def extract_version(version_str: str) -> Tuple[Optional[Version], int, int]:
 
 def increment_version(version_str: str, rel_seg: int = None, pre_seg: str = None) -> str:
     """
-    Increment the PEP440 version number in a string
+    Increment the :pep:`440` version number in a string
 
     :param version_str: The input string to manipulate
     :param rel_seg: Which segment of the "release" value to increment, if any
@@ -76,7 +76,7 @@ def increment_version(version_str: str, rel_seg: int = None, pre_seg: str = None
 
 
 def join_version(epoch, release, pre, post, dev, local) -> str:
-    """Join multiple segments of a PEP440 version"""
+    """Join multiple segments of a :pep:`440` version"""
     parts = []
 
     # Epoch
@@ -106,7 +106,13 @@ def join_version(epoch, release, pre, post, dev, local) -> str:
 
 
 def is_release(version_str: str) -> bool:
-    """Check if a version string is a release version or not. Returns false if a PEP440 version could not be found"""
+    """
+    Check if a version string is a release version
+
+    :param version_str: the input string to check
+    :return: True if the input contains a released :pep:`440` version,
+        or False if a prerelease version or no version is found
+    """
     v, *span = extract_version(version_str)
     if v:
         return not (v.is_devrelease or v.is_prerelease)