diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index b41f71b..2170389 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -77,10 +77,11 @@ jobs: password: ${{ secrets.PYPI_API_TOKEN }} - name: Publish to Github - uses: softprops/action-gh-release@v2 - with: - files: dist/* - name: ${{ steps.yaclog-show.outputs.name }} - body_path: ${{ steps.yaclog-show.outputs.body_file }} + 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 }} \ No newline at end of file diff --git a/action.yaml b/action.yaml index 4f7473a..2b38022 100644 --- a/action.yaml +++ b/action.yaml @@ -15,13 +15,7 @@ inputs: 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 be pushed back to the repo, but the workflow must have write permissions. - Add - ```yaml - permissions: - contents: write - ``` - to your workflow to allow this. + The resulting commit and tag will NOT be pushed back to the repo. You must add a step to do this yourself outputs: name: @@ -68,15 +62,4 @@ runs: # header=Version 1.3.0 - 2024-08-08 # version=1.3.0 # body_file={path to file containing version body} - # changelog={path to changelog} - - - name: Push Changes - if: ${{ inputs.release }} - shell: bash - env: - GH_TOKEN: ${{ github.token }} - run: | - git config --global user.name "github-actions" - git config --global user.email "github-actions@github.com" - git push - git push --tags + # changelog={path to changelog} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index d73e674..e7356b5 100644 --- a/docs/conf.py +++ b/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, +} \ No newline at end of file diff --git a/docs/handbook/github_actions.md b/docs/handbook/github_actions.md new file mode 100644 index 0000000..eafd899 --- /dev/null +++ b/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 }}' }} +``` +```` \ No newline at end of file diff --git a/docs/handbook/index.md b/docs/handbook/index.md index 94643a3..e7ac976 100644 --- a/docs/handbook/index.md +++ b/docs/handbook/index.md @@ -8,4 +8,5 @@ maxdepth: 3 getting_started changelog_files commands +github_actions ``` \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index d4cb2a5..48c7e12 100644 --- a/pyproject.toml +++ b/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]