diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css index a51b44a..1efdb90 100644 --- a/docs/_static/css/custom.css +++ b/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 */ } \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 2ddee8f..d73e674 100644 --- a/docs/conf.py +++ b/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'] diff --git a/docs/handbook/commands.md b/docs/handbook/commands.md new file mode 100644 index 0000000..b42f164 --- /dev/null +++ b/docs/handbook/commands.md @@ -0,0 +1,7 @@ +# Command Reference + +```{eval-rst} +.. click:: yaclog.cli.__main__:cli + :prog: yaclog + :nested: full +``` \ No newline at end of file diff --git a/docs/handbook/getting_started.md b/docs/handbook/getting_started.md new file mode 100644 index 0000000..64bdf82 --- /dev/null +++ b/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". +``` diff --git a/docs/handbook/index.md b/docs/handbook/index.md new file mode 100644 index 0000000..2cac5da --- /dev/null +++ b/docs/handbook/index.md @@ -0,0 +1,11 @@ +# Handbook + +```{toctree} +--- +maxdepth: 2 +glob: +--- + +getting_started +commands +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4b73142 --- /dev/null +++ b/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 +License +``` + +## Indices and tables + +* {ref}`genindex` +* {ref}`modindex` +* {ref}`search` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 36949c0..0000000 --- a/docs/index.rst +++ /dev/null @@ -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 - -.. toctree:: - :maxdepth: 1 - - Changelog - License - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/yaclog/cli/__main__.py b/yaclog/cli/__main__.py index f0a8393..ad98c50 100644 --- a/yaclog/cli/__main__.py +++ b/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): diff --git a/yaclog/version.py b/yaclog/version.py index 9439995..5d14f64 100644 --- a/yaclog/version.py +++ b/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)