Release Version 1.4.0

### Added

- added a github action to the repository. The action can create new releases and fetch version information. For mor information see the "Github Actions" page in the handbook

.github/workflows/python-publish.yml

@@ -26,9 +26,6 @@ jobs:
           python -m pip install flake8
           python -m pip install ${{ matrix.click-version }}
 
-      - name: Install module
-        run: python -m pip install .
-
       - name: Lint with flake8
         run: |
           # stop the build if there are Python syntax errors or undefined names
@@ -36,9 +33,16 @@ jobs:
           # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
           flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
 
-      - name: Run unit tests
+      - name: Install module
+        run: python -m pip install .
+
+      - name: Run Unit Tests
         run: python -m unittest -v
 
+      - name: Run Action
+        id: yaclog-show
+        uses: ./
+
   deploy:
     needs: test
     runs-on: ubuntu-latest
@@ -56,7 +60,6 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install setuptools wheel twine
-          python -m pip install . # Self hosting!
 
       - name: Install pypa/build
         run: python -m pip install build --user
@@ -64,10 +67,9 @@ jobs:
       - name: Build a binary wheel and source tarball
         run: python -m build --sdist --wheel --outdir dist/
 
-      - name: Get version name and body
-        run: |
-          echo "VERSION_TILE=$(yaclog show -n)" >> $GITHUB_ENV
-          echo "$(yaclog show -mb)" >> RELEASE.md
+      - name: Get version info
+        id: yaclog-show
+        uses: ./
 
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
@@ -75,10 +77,11 @@ jobs:
           password: ${{ secrets.PYPI_API_TOKEN }}
 
       - name: Publish to Github
-        uses: softprops/action-gh-release@v2
-        with:
-          files: dist/*
-          name: ${{ env.VERSION_TITLE }}
-          body_path: RELEASE.md
+        run: |
+          gh release create ${{ github.ref_name }} \
+            --notes-file "${{ steps.yaclog-show.outputs.body_file }}" \
+            --title "${{ steps.yaclog-show.outputs.name }}"
+          
+          gh release upload ${{ github.ref_name }} dist/*
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ github.token }}

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file
 
+## Version 1.4.0 - 2024-08-25
+
+### Added
+
+- added a github action to the repository. The action can create new releases and fetch version information. For mor information see the "Github Actions" page in the handbook
+
+
 ## Version 1.3.0 - 2024-08-08
 
 ### Added

action.yaml

@@ -0,0 +1,65 @@
+name: Yaclog
+description: > 
+  Get version information from a changelog, and optionally create a new release. 
+  The `yaclog` command is made available for use in future steps.
+branding:
+  icon: file-text
+  color: orange
+
+inputs:
+  markdown:
+    description: If outputs should be in markdown format or not
+    default: 'true'
+
+  release:
+    description: > 
+      Creates a new release and commits it if set. Directly passed to the arguments of `yaclog release`. 
+      Can be a version number or an increment tag like `--major`, `--minor`, or `--patch`. 
+      The resulting commit and tag will NOT be pushed back to the repo. You must add a step to do this yourself
+
+outputs:
+  name:
+    description: "The current version name. For example, `Version 1.3.0`"
+    value: ${{ steps.yaclog-show.outputs.name}}
+  header:
+    description: "The entire header for the current version. For example, `Version 1.3.0 - 2024-08-08`"
+    value: ${{ steps.yaclog-show.outputs.header }}
+  version:
+    description: "The current version number. For example, `1.3.0`"
+    value: ${{ steps.yaclog-show.outputs.version }}
+  body_file:
+    description: "Path to a temporary file containing the version body"
+    value: ${{ steps.yaclog-show.outputs.body_file }}
+  changelog:
+    description: "Path to the entire changelog file."
+    value: ${{ steps.yaclog-show.outputs.changelog }}
+
+runs:
+  using: "composite"
+  steps:
+    - id: setup-python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+        update-environment: 'false'
+
+    - name: Setup Yaclog
+      shell: bash
+      run: pipx install --python ${{ steps.setup-python.outputs.python-path }} ${{ github.action_path }}
+
+    - name: Create New Release
+      shell: bash
+      if: ${{ inputs.release }}
+      run: yaclog release --yes --commit ${{ inputs.release }}
+
+    - name: Get Version Information
+      id: yaclog-show
+      shell: bash
+      run: |
+        yaclog show ---gh-actions ${{ inputs.markdown && '--markdown' }} >> "$GITHUB_OUTPUT"
+        # output like so:
+        #  name=Version 1.3.0
+        #  header=Version 1.3.0 - 2024-08-08
+        #  version=1.3.0
+        #  body_file={path to file containing version body}
+        #  changelog={path to changelog}

docs/conf.py

@@ -4,7 +4,7 @@
 # list see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-from pkg_resources import get_distribution
+from importlib.metadata import version
 
 # -- Path setup --------------------------------------------------------------
 
@@ -22,8 +22,9 @@ sys.path.insert(0, os.path.abspath('..'))
 project = 'Yaclog'
 copyright = '2021, Andrew Cassidy'
 author = 'Andrew Cassidy'
-release = get_distribution('yaclog').version
+release = version('yaclog')
 version = '.'.join(release.split('.')[:3])
+ref = version if len(release.split('.')) == 3 else 'main'
 
 # -- General configuration ---------------------------------------------------
 
@@ -36,9 +37,13 @@ extensions = [
     'sphinx_rtd_theme',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinx_jinja'
 ]
 
 myst_heading_anchors = 2
+myst_enable_extensions = [
+    "colon_fence"
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -76,6 +81,8 @@ autodoc_default_options = {
     'undoc-members': True,
 }
 
+
+
 # -- Options for Intersphinx -------------------------------------------------
 
 # This config value contains the locations and names of other projects that
@@ -85,3 +92,9 @@ intersphinx_mapping = {
     'python': ('https://docs.python.org/3', None),
     'packaging': ('https://packaging.pypa.io/en/latest/', None),
 }
+
+jinja_globals = {
+    'version': version,
+    'release': release,
+    'ref': ref,
+}

docs/handbook/github_actions.md

@@ -0,0 +1,141 @@
+# Github Actions
+
+Yaclog makes an action available for Github Actions and compatible CI systems.
+
+## The Yaclog Action
+
+To use the Yaclog action add the following to your workflow steps
+
+````{jinja}
+```yaml
+      - name: Get version info
+        uses: drewcassidy/yaclog@{{ ref }}
+        id: yaclog
+```
+````
+
+### Inputs
+
+```{confval} release
+:type: string
+
+  When set, creates a new release and commits it. Directly passed to the arguments of `yaclog release --yes --commit`.
+
+  Can be a version number or an increment tag like `--major`, `--minor`, or `--patch`.
+  The resulting commit and tag will NOT be pushed back to the repo. You must add a step to do this yourself
+```
+
+```{confval} markdown
+:type: boolean
+:default: true
+
+If the output should be in markdown format or not. Equivalent to the `--markdown` flag
+```
+
+### Outputs
+
+```{confval} version
+The current version number, equivalent to the output of `yaclog show --version`. For example, `1.3.1`
+```
+
+```{confval} name
+The most recent version name, equivalent to the output of `yaclog show --name`. For example, `Version 1.3.0`
+```
+
+```{confval} header
+The entire header for the most recent version, equivalent to the output of `yaclog show --header`. For example, `Version 1.3.0 - 2024-08-08`
+```
+
+```{confval} body_file
+The path to a temporary file containing the body of the most recent version. Contents equivalent to `yaclog show --body`
+```
+
+```{confval} changelog
+The path to the changelog file. Usually `CHANGELOG.md` in the current directory.
+```
+
+## Example Usage
+
+### Get changelog information in your Build workflow
+
+````{jinja}
+```yaml
+name: Build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Mod Repo
+        uses: actions/checkout@v4
+        
+      - uses: drewcassidy/yaclog@{{ ref }}
+        id: yaclog
+        
+      # Your build and test actions go here
+        
+      - name: Publish to Github
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+        run: |
+          gh release create {{ '${{ github.ref_name }}' }} \
+            --notes-file "{{ '${{ steps.yaclog.outputs.body_file }}' }}" \
+            --title "{{ '${{ steps.yaclog.outputs.name }}' }}" 
+        env:
+          GH_TOKEN: {{ '${{ github.token }}' }}
+
+```
+````
+
+### Workflow to make a new release
+
+If you want to be able to create a new release for your project directly from the Github UI, you can make a new workflow
+you can dispatch directly. 
+
+Please note that this workflow does NOT create any releases in Github or any package managers. Instead, your normal build workflow should do this when it detects a push to a tag.
+
+````{jinja}
+```yaml
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      release:
+        description: 'type of release to use'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+        - major 
+        - minor
+        - patch
+
+permissions:
+  contents: write
+
+jobs:
+  yaclog-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Mod Repo
+        uses: actions/checkout@v4
+      
+      - name: Yaclog Release
+        uses: drewcassidy/yaclog@{{ ref }}
+        with: 
+          release: '--{{ '${{ inputs.release }}' }}'
+          
+      - name: Push Changes
+        run: |
+          git config --global user.name "github-actions"
+          git config --global user.email "github-actions@github.com"
+          git push
+          git push --tags
+        env:
+          GH_TOKEN: {{ '${{ github.token }}' }}
+```
+````

docs/handbook/index.md

@@ -8,4 +8,5 @@ maxdepth: 3
 getting_started
 changelog_files
 commands
+github_actions
 ```

pyproject.toml

@@ -43,6 +43,7 @@ docs = [
     "sphinx-click >= 2.7",
     "sphinx-rtd-theme",
     "myst-parser >= 0.14",
+    "sphinx-jinja >=1.2.1",
 ]
 
 [project.scripts]

yaclog/cli/__main__.py

@@ -72,9 +72,10 @@ def reformat(obj: Changelog):
               help='Show only the version header.')
 @click.option('--version', '-v', 'mode', flag_value='version', help='Show only the version number. If the current version is unreleased, '
                                                                     'this is inferred by incrementing the patch number of the last released version')
+@click.option('---gh-actions', 'gh_actions', is_flag=True, hidden=True)
 @click.argument('version_names', metavar='VERSIONS', type=str, nargs=-1)
 @click.pass_obj
-def show(obj: Changelog, all_versions, markdown, mode, version_names):
+def show(obj: Changelog, all_versions, markdown, mode, version_names, gh_actions):
     """
     Show the changes for VERSIONS.
 
@@ -110,6 +111,20 @@ def show(obj: Changelog, all_versions, markdown, mode, version_names):
         raise click.ClickException(str(v))
 
     sep = '\n\n' if mode == 'body' or mode == 'full' else '\n'
+
+    if gh_actions:
+        import tempfile
+
+        all_modes = [ 'name', 'header', 'version' ]
+        outputs = [f'{mode}={sep.join([functions[mode](v, kwargs) for v in versions])}' for mode in all_modes]
+        click.echo('\n'.join(outputs))
+        body_fd, body_file = tempfile.mkstemp(text=True)
+        with os.fdopen(body_fd, 'w') as f:
+            f.write(sep.join([functions['body'](v, kwargs) for v in versions]))
+        click.echo(f'body_file={body_file}')
+        click.echo(f'changelog={obj.path}')
+        return
+
     click.echo(sep.join([str_func(v, kwargs) for v in versions]))