Accumulated updates for Github Action / python package usage

rkdarst · rkdarst · commit e75af39278db · 2025-08-27T23:17:10.000+03:00
diff --git a/README.md b/README.md
@@ -1,70 +1,128 @@
-# yaml to ics calendar
+# YAML to ics calendar
 
-This repository turns yaml files into icl calendars (importable into
+This repository turns yaml files into .ics calendars (importable into
 different programs) using
 [yaml2ics](https://github.com/scientific-python/yaml2ics) and GitHub
-actions.
+actions.  Or, you can use git-calendar directly.
 
 This repository provides a working template for the action to build +
-publish to Github Pages, and some minimal HTML index pages.  All of
-the important logic is in
+publish to Github Pages, including files into other files, and some
+minimal HTML index pages.  All of the important logic is in
 [yaml2ics](https://github.com/scientific-python/yaml2ics), so if you
 want to roll your own site and build system (which isn't hard) for the
 .ics files, consider using yaml2ics directly.
 
-This is sort of alpha: it works and is used, but code editing or
-asking for clarifications is probably needed.  Documentation should be
-improved.
 
 
-
-## Example
+## Example deployments
 
 The CodeRefinery calendar
 * [Built calendar site](https://coderefinery.github.io/calendar/)
-  (main landing page for most projects)
+  (the auto-generated landing page)
 * [Source repository](https://github.com/coderefinery/calendar)
 * Optional: [Calendars inserted into
   website](https://coderefinery.org/calendars/) ([source](https://github.com/coderefinery/coderefinery.org/blob/main/content/calendars.md))
 
 
 
-## Usage
+## General principles
 
-To use, look at
-[git-calendar-template](https://github.com/coderefinery/git-calendar-template)
-for a sample repository that uses this.  Generate your own repository
-from that template and go from there.
+One defines events in YAML, and they get built to `.ics` files which
+can be served as a static site.  These can then be imported to various
+calendar clients.
 
-This repository can also be installed as a Python pip package.
+There's a command line program, `git-calendar`, which takes YAML files
+as input (one of which can be named `_config.yaml`).  The last
+argument is the output directory to which to write.
 
-Usage in short:
+A typical repository layout:
 
 - `calendars/*.yaml` contains the input calendars.
-- `./build.sh` builds the outputs.  Edit this script as
-  needed, or copy the command to your own build script.
-  - `out/index.html` gets build and serves as a landing page
-  - Calendars get build to `out/*.ics`
-  - The Github Actions workflow file deploys `out/` to the `gh-pages`
-  branch.
-
-- **First time deployment note:** you have to go to settings and
-  toggle pages off and on again the first time to enable Github Pages,
-  after that Github Actions will automatically deploy.
+- `output/` is the web root for web deployment
+- `output/*.ics` is the build calendars
+- `output/index.html` gets built and serves as a landing page with
+  links to the .ics files
 
 For now, see `calendars/example.yaml` for an example, or any of the
 test calendars in yaml2ics.  This documentation should be improved.
 
 
 
+## Usage - Github action
+
+This can be used as Github action (see EXAMPLE REPO for the full file).
+
+```yaml
+      - uses: actions/checkout@v4
+      - name: git-calendar action
+        uses: coderefinery/git-calendar@action-test
+        with:
+          input_dir: calendars    # the default, not required
+          output_dir: output      # the default, not required
+          index_file: index.html  # the default, set to '' to not
+        create
+        htmlbody_file: body.html  # Only the part inside <body> for inclusion in other files
+```
+
+This action will automatically deploy to Github Pages.  You can set
+`with: pages_deploy: false` to disable this.  The action will also
+setup Python and install this Python library.  If you already set up
+Python, it may be easier to code up your own action than use this.
+
+
+
+## Usage - Raw Github action
+
+If you want to program the action yourself, below is the base.  You
+probably can probably figure out how to integrate this to a Github
+Pages deployment and all.
+```yaml
+    - name: build
+      shell: bash
+      run: |
+        git-calendar calendars/*.yaml output/ --index=index.html --edit-link=https://github.com/$GITHUB_REPOSITORY
+```
+
+
+
+## Usage - command line
+
+This is a Python package, install as normal (yes, in a virtual environment, etc...):
+```console
+$ pip install git-calendar
+```
+
+Then run:
+
+```console
+$ git-calendar calendars/*.yaml output/ --index=index.html --edit-link=https://github.com/$GITHUB_REPOSITORY
+```
+
+There are more options, not currently documented.
+
+
+
+## Usage - via raw yaml2ics
+
+Don't forget this is just a wrapper around
+[yaml2ics](https://github.com/scientific-python/yaml2ics) - if you
+only need a .ics file and not index.html, including calendars in
+others, etc., then maybe that is your starting point:
+
+```console
+$ python yaml2ics.py example/test_calendar.yaml example/another_calendar.yaml > out.ics
+```
+
+
+
 ## Status
 
-Alpha, it works but may require code changes still to get around
-corner cases.
+Beta as of 2025, it works but may require code changes still to get
+around corner cases.  As of 2025 issues will probably be responded to.
 
 
 
-## See Also
+## See also
 
 * This directly uses https://github.com/scientific-python/yaml2ics as
   the yaml to ical generator - if you want to create your own build
diff --git a/action.yml b/action.yml
@@ -0,0 +1,59 @@
+# CC-0 (public domain)
+# but please link to the source so that people can more easily reuse
+# (if relevant)
+
+name: git-calendar
+description: Manage multiple branches in gh-pages
+
+inputs:
+  calendars:
+    description: 'Input calendar directory (default calendars, globs *.yaml from there)'
+    default: 'calendars/*.yaml'
+  output_dir:
+    description: 'Output directory (default output/)'
+    default: 'output/'
+  extra_options:
+    description: 'extra options to git-calendar build.  Example: --timezone=Europe/Helsinki --timezone=Europe/Stockholm'
+    default: ''
+  index_file:
+    default: index.html
+  html_body_file:
+    default: body.html
+  pages_deploy:
+    description: "Deploy to GitHub pages.  Use only if you don't have another pages deployment.  Default: true."
+    default: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install dependencies
+      shell: bash
+      run: |
+        #pip install https://github.com/coderefinery/git-calendar/archives/main.zip
+        pip install ${{ github.action_path }}
+    - name: build
+      shell: bash
+      run: |
+        git-calendar\
+            ${{ inputs.calendars }} \
+            ${{ inputs.output_dir}} \
+            --edit-link=https://github.com/$GITHUB_REPOSITORY \
+            ${{ inputs.index_file && format('--index={0}', inputs.index_file) }} \
+            ${{ inputs.html_body_file && format('--html-body={0}', inputs.html_body_file) }} \
+            ${{ inputs.extra_options }}
+    - name: List outputs
+      shell: bash
+      run: |
+        find ${{ inputs.output_dir }} | sort
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: ${{ inputs.output_dir }}
+    - name: Deploy to GitHub Pages
+      uses: actions/deploy-pages@v4
+      if: ${{ inputs.pages_deploy }}
+
diff --git a/build.sh b/build.sh
diff --git a/git_calendar/build.py b/git_calendar/build.py
@@ -19,14 +19,16 @@
 def main(argv=sys.argv[1:]):
     parser = argparse.ArgumentParser()
     parser.add_argument('inputs', nargs='+', help="input files", type=Path)
-    parser.add_argument('--output', '-o', help="output directory", type=str)
+    parser.add_argument('output', help="output directory", type=str)
     parser.add_argument('--index', '-i', help="output HTML index file", type=str)
     parser.add_argument('--html-body', '-b', help="output HTML body to be included in other pages", type=str)
     parser.add_argument('--timezone', action='append', help="zoneinfo timezone names", type=str, default=[])
     parser.add_argument('--edit-link', help='Link to edit, will be added to the generated page.')
     parser.add_argument('--base-url', help='Base url to append in front of all .ics files '
                         '(include trailing slash).',
                         default='')
+    parser.add_argument('--jinja-template-dir', help='Jinja template dir.  See source for a starting point',
+                        action='append', default=[])
     args = parser.parse_args(argv)
 
     calendars = [ ]
@@ -53,22 +55,27 @@ def main(argv=sys.argv[1:]):
         output = join(args.output, fics)
 
         calendar = yaml2ics.files_to_calendar([f])
+        print(f"Writing {f} --> {output}")
         open(output, 'w').write(calendar.serialize())
 
         # Generate the rendered views in different timezones
         for tzdata in timezones:
             # text file dump:, may be useful for some people.
             # This is clearly a hack, calling the shell commands.  This should
             # be improved later.
+            print(f"Writing {f} (in {tzdata['tz']}) --> out/{fics}.{tzdata['tzslug']}.txt")
             subprocess.check_output(
-                fr"TZ={tzdata['tz']} mutt-ics out/{fics}  | sed 's/^Subject:/\n\n----------\nSubject:/' > out/{fics}.{tzdata['tzslug']}.txt",
+                fr"TZ={tzdata['tz']} mutt-ics {args.output}/{fics}  | sed 's/^Subject:/\n\n----------\nSubject:/' > {args.output}/{fics}.{tzdata['tzslug']}.txt",
                 shell=True)
             # Convert to an .ics file in different timezones.  This shouldn't
             # be needed, but it seems that Thunderbird doesn't convert
             # timezones so this is useful for it.
             calendarTZ = calendar.clone()
             calendarTZ.normalize(gettz(tzdata['tz']))
-            open(join(args.output, fbase+'.'+tzdata['tzslug']+'.ics'), 'w').write(calendarTZ.serialize())
+
+            output_tz_txt = join(args.output, fbase+'.'+tzdata['tzslug']+'.ics')
+            print(f"Writing {f}[{tzdata['tz']}] --> {output_tz_txt}")
+            open(output_tz_txt, 'w').write(calendarTZ.serialize())
 
 
 
@@ -78,37 +85,34 @@ def main(argv=sys.argv[1:]):
         git_hash = subprocess.check_output(["git", "rev-parse", "--short", "HEAD"], encoding='utf8').strip()
 
         env = jinja2.Environment(
-            loader=jinja2.FileSystemLoader([TEMPLATE_DIR]),
+            loader=jinja2.FileSystemLoader(args.jinja_template_dir + [TEMPLATE_DIR]),
             autoescape=jinja2.select_autoescape(['html', 'xml', '.j2.html',]),
         )
         env.filters['markdown'] = markdown_it.MarkdownIt().render
-
-    if args.index:
-        template = env.get_template('index.j2.html')
-        print(f'Writing index to {args.index}', file=sys.stderr)
-        index = template.render(
+        template_context = dict(
             calendars=calendars,
             timezones=timezones,
             timestamp=timestamp,
             git_hash=git_hash,
             edit_link=args.edit_link,
             config=config,
             )
-        shutil.copy(TEMPLATE_DIR/'style.css', Path(args.index).parent/'style.css')
-        open(args.index, 'w').write(index)
+
+    if args.index:
+        index_file = join(args.output, args.index)
+        print(f'Writing index to {index_file}', file=sys.stderr)
+        index    = env.get_template('index.j2.html').render(template_context)
+        stylecss = env.get_template('style.css').render(template_context)
+        with open(index_file, 'w') as f_index, open(join(args.output, 'style.css'), 'w') as f_style:
+            f_style.write(stylecss)
+            f_index.write(index)
 
     if args.html_body:
+        htmlbody_file = join(args.output, args.html_body)
         template = env.get_template('body.j2.html')
-        print(f'Writing HTML to {args.html_body}', file=sys.stderr)
-        with open(args.html_body, 'w') as f:
-            html = template.render(
-                calendars=calendars,
-                timezones=timezones,
-                timestamp=timestamp,
-                git_hash=git_hash,
-                edit_link=args.edit_link,
-                config=config,
-                )
+        print(f'Writing HTML to {htmlbody_file}', file=sys.stderr)
+        with open(htmlbody_file, 'w') as f:
+            html = template.render(template_context)
             f.write(html)
 
 
diff --git a/git_calendar/templates/body.j2.html b/git_calendar/templates/body.j2.html
@@ -25,7 +25,7 @@ <h2>Available calendars</h2>
     )
     {%- endif %}
     {% if c.data.links -%}
-    ( {%- for href, text in c.data.links %}<a href="{{href}}">{{text}}</a>{% endfor %}{%if not loop.last%}, {% endif -%}
+    ( {%- for href, text in c.data.links %}<a href="{{href}}">{{text}}</a>{%if not loop.last%}, {% endif %}{% endfor -%}
     )
     {%- endif %}
   </li>
diff --git a/git_calendar/yaml2ics.py b/git_calendar/yaml2ics.py
@@ -224,9 +224,9 @@ def files_to_events(files: list, dirname: str = "") -> (ics.Calendar, str):
     all_events = []
     name = None
     processed_files, temporary_files = gather_files(files, dirname=dirname)
-    print(processed_files)
-    print(files)
-    print(dirname)
+    #print(processed_files)
+    #print(files)
+    #print(dirname)
     for f in processed_files:
         print(f"Processing {f}")
         # If it is a raw ICS file
diff --git a/pyproject.toml b/pyproject.toml
@@ -10,16 +10,16 @@ license = {file = "LICENSE"}
 classifiers = ["License :: OSI Approved :: MIT License"]
 dynamic = ["version", "description"]
 dependencies = [
-    #"yaml2ics",
-    "yaml2ics @ https://github.com/scientific-python/yaml2ics/archive/refs/heads/main.zip",
+    #"yaml2ics",  # now vendored
+    #"yaml2ics @ https://github.com/scientific-python/yaml2ics/archive/refs/heads/main.zip",
     "python-dateutil",
     "jinja2",
     "mutt-ics",
     "pyyaml",
     "markdown-it-py",
-    # TODO: how to install from github here?  Then remove this
-    # from requirements.txt
-    "ics @ https://github.com/ics-py/ics-py/archive/refs/heads/main.zip",
+    # There is some new unreleased ics-py feature needed.  As of 2025,
+    # last release was in 2022.
+    "ics @ https://github.com/ics-py/ics-py/archive/3b7d072.zip",  # main probably works too
 ]
 
 [project.scripts]

Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@ <h2>Available calendars</h2>`
`25`	`25`	`)`
`26`	`26`	`{%- endif %}`
`27`	`27`	`{% if c.data.links -%}`
`28`		`- ( {%- for href, text in c.data.links %}<a href="{{href}}">{{text}}</a>{% endfor %}{%if not loop.last%}, {% endif -%}`
	`28`	`+ ( {%- for href, text in c.data.links %}<a href="{{href}}">{{text}}</a>{%if not loop.last%}, {% endif %}{% endfor -%}`
`29`	`29`	`)`
`30`	`30`	`{%- endif %}`
`31`	`31`	`</li>`