Merge pull request #22 from williln/fix-internal-readmes

Fix internal readmes

Author: williln

.github/workflows/build.yml

@@ -46,6 +46,7 @@ jobs:
           python3 scripts/build_subdir_toc.py github
           python3 scripts/build_subdir_toc.py google
           python3 scripts/build_subdir_toc.py home-office
+          python3 scripts/build_subdir_toc.py html
           python3 scripts/build_subdir_toc.py htmx
           python3 scripts/build_subdir_toc.py javascript
           python3 scripts/build_subdir_toc.py kubernetes
@@ -54,15 +55,23 @@ jobs:
           python3 scripts/build_subdir_toc.py meilisearch
           python3 scripts/build_subdir_toc.py microsoft-dynamics
           python3 scripts/build_subdir_toc.py misc
+          python3 scripts/build_subdir_toc.py mkdocs
+          python3 scripts/build_subdir_toc.py plata
+          python3 scripts/build_subdir_toc.py postgres
+          python3 scripts/build_subdir_toc.py pre-commit
           python3 scripts/build_subdir_toc.py pytest
           python3 scripts/build_subdir_toc.py python
           python3 scripts/build_subdir_toc.py r
+          python3 scripts/build_subdir_toc.py seo
           python3 scripts/build_subdir_toc.py slack
+          python3 scripts/build_subdir_toc.py sphinx
+          python3 scripts/build_subdir_toc.py stripe
+          python3 scripts/build_subdir_toc.py terraform
           python3 scripts/build_subdir_toc.py wagtail
       - name: Commit and push if anything changed
         run: |-
           git diff
           git config --global user.email "[email protected]"
           git config --global user.name "README-bot"
-          git diff --quiet || (git add README.md && git commit -m "Updated READMEs")
+          git diff --quiet || (git add README.md */README.md && git commit -m "Updated READMEs")
           git push

.gitignore

@@ -1 +1,2 @@
 /til.db
+.aider*

README.md

@@ -1,27 +1,28 @@
 # til
 
-My repo of Today I Learned posts. Inspired by [simonw/til](https://github.com/simonw/til). 
+My repo of Today I Learned posts. Inspired by [simonw/til](https://github.com/simonw/til).
 
-**Now**: July 2024: At some point this month, I set a goal to write a TIL every work day. I haven't stuck to that, but I am averaging several per week, and I'm pleased with the cadence. But even trying to post every day, I am still not capturing everything I've learned. 
+**Now**: April 2025: I have really fallen out of the habit of writing these TILs. But I am still learning so much, so I'm going to start trying to get back into the practice. I still believe in the power of the TIL!
 
-## My TIL Philosophy 
+## My TIL Philosophy
 
-Since this repo has a few stars ⭐ (hi everyone), I want to take a moment to set expectations. 
+Since this repo has a few stars ⭐ (hi everyone), I want to take a moment to set expectations.
 
 - I write TILs quickly, usually in under 10 minutes.
 - Usually, there isn't any editing other than light proofreading.
 - I really enjoy it! Highly recommend a public TIL repo as a personal practice.
 - Sometimes I share them on Mastodon, but not always.
 
-## Benefits of my TIL repo 
+## Benefits of my TIL repo for myself
 
-- It's good, low-stakes writing practice. 
-- It helps remind me that beginnerhood is perpetual. 
-- I have a few of my own TILs that I consult really regularly. Nothing beats copying and pasting your own stuff forever. 
-- Sometimes, the TILs get picked up by [Django News](https://django-news.com/issues/243?#start), and that's neat! 
+- It's good, low-stakes writing practice.
+- It helps remind me that beginnerhood is perpetual.
+- I have a few of my own TILs that I consult really regularly. Nothing beats copying and pasting your own stuff forever.
+- Sometimes, the TILs get picked up by [Django News](https://django-news.com/issues/243?#start), and that's neat!
 - Other people are aware of what I am working on, and then ask for help related to those things. Feels great to help people.
 - It provides a neat fossil record of the kinds of things I've worked on over the course of my career.
-- I have a repo full of markdown that's easy to clone and run parsing experiments on. 
+- I have a repo full of markdown that's easy to clone and run parsing experiments on, which has come in handy a few times for client work.
+- I break down a lot of concepts into small pieces for myself, which makes writing longer-form pieces easier.
 
 ---
 
@@ -264,3 +265,19 @@ Since this repo has a few stars ⭐ (hi everyone), I want to take a moment to se
 * [Seeding my Wagtail site](https://github.com/williln/til/blob/main/wagtail/seeding_wagtail_site.md) - 2024-03-27
 * [What to do if you delete the default Wagtail homepage](https://github.com/williln/til/blob/main/wagtail/fix_deleted_root_page.md) - 2024-03-25
 <!-- index ends -->
+
+<!-- docs-section starts -->
+
+## Automatic README Generation
+
+This repository uses GitHub Actions to automatically generate and update README files:
+
+1. The main README.md (this file) is updated with:
+   - A table of contents listing all topics
+   - An index of all TIL posts organized by topic
+
+2. Each subdirectory also gets its own README.md with links to all files in that directory.
+
+These updates happen automatically whenever changes are pushed to the main branch.
+
+<!-- docs-section ends -->

django/README.md

@@ -15,6 +15,7 @@
 - [How to confirm that login is required in your Django view](how_to_test_view_auth.md)
 - [How to log in a test user in a `pytest` unit test](test_protected_page.md)
 - [How to test a file upload with `pytest` and `SimpleUploadedFile`](testing_file_upload_pytest.md)
+- [Neapolitan: Everything I've Learned](neapolitan.md)
 - [Run SQL statements as part of your migrations with `migrations.RunSQL`](run_sql.md)
 - [Testing Django signals, and disabling signals in tests (Django 2.2)](testing_django_signals.md)
 - [Using Django Aggregation](aggregation.md)

git/README.md

@@ -1,3 +1,6 @@
 # git
 
-- [Moving from an old repo to a new repo in another organization](moving_to_a_new_repo.md)
+- [Checking out someone else's branch](check_out_remote_branch.md)
+- [Moving from an old repo to a new repo in another organization](moving_to_a_new_repo.md)
+- [Naming a `git stash` and re-applying it later](name_a_stash_and_apply_it.md)
+- [`git reset`, with `soft`: Undo your last commit but keep your changes](undo_commit_but_preserve_changes.md)

justfile

@@ -23,12 +23,15 @@ build-internal-readmes:
     python3 scripts/build_subdir_toc.py microsoft-dynamics
     python3 scripts/build_subdir_toc.py misc
     python3 scripts/build_subdir_toc.py mkdocs
+    python3 scripts/build_subdir_toc.py plata
     python3 scripts/build_subdir_toc.py postgres
     python3 scripts/build_subdir_toc.py pre-commit
     python3 scripts/build_subdir_toc.py pytest
     python3 scripts/build_subdir_toc.py python
     python3 scripts/build_subdir_toc.py r
+    python3 scripts/build_subdir_toc.py seo
     python3 scripts/build_subdir_toc.py slack
+    python3 scripts/build_subdir_toc.py sphinx
     python3 scripts/build_subdir_toc.py stripe
     python3 scripts/build_subdir_toc.py terraform
-    python3 scripts/build_subdir_toc.py wagtail
+    python3 scripts/build_subdir_toc.py wagtail

kubernetes/README.md

@@ -1,4 +1,5 @@
 # kubernetes
 
 - [Accessing a Kubernetes cluster for the first time](accessing_cluster.md)
-- [Setting up Kubernetes access on MacOS with a config file](setting_up_new_access_mac.md)
+- [Setting up Kubernetes access on MacOS with a config file](setting_up_new_access_mac.md)
+- [Viewing logs for your pod](viewing_logs.md)

plata/README.md

@@ -0,0 +1,3 @@
+# plata
+
+- [[`plata`](https://github.com/matthiask/plata/) order processors](processors.md)

python/README.md

@@ -7,4 +7,5 @@
 - [How to sort a Python dictionary by key or value](sort_dictionary.md)
 - [How to sort a Python dictionary by multiple values](sort_dict_multiple_keys.md)
 - [Using `Decimal.quantize`](decimal_quantize.md)
-- [Using `pip-tools` and `pip-compile` for Python dependency management](pip_tools.md)
+- [Using `pip-tools` and `pip-compile` for Python dependency management](pip_tools.md)
+- [`typing.final`](typing-final.md)

scripts/build_subdir_toc.py

@@ -4,45 +4,51 @@
 
 
 @click.command()
-@click.argument("directory", type=click.Path(exists=True))
+@click.argument("directory", type=click.Path())
 def generate_readme_links(directory):
     """
     Generate a README file with clickable links to all files in the specified directory.
 
     DIRECTORY: The path to the directory containing files.
     """
+
     readme_file = os.path.join(directory, "README.md")
 
     with open(readme_file, "w") as f:
         # Use first h1 as the header
         header = os.path.basename(directory)
         f.write(f"# {header}\n\n")
 
-        for root, dirs, files in os.walk(directory):
-            contents = []
-            for file in files:
-                title = None
-                # Read the file so I can get the header, which contains the title.
-                with open(os.path.join(root, file), "r") as file_obj:
-                    title = file_obj.readline().replace("#", "").strip()
+        # Only process files if the directory exists and has files
+        if os.path.exists(directory):
+            for root, dirs, files in os.walk(directory):
+                contents = []
+                for file in files:
+                    # Skip the README file
+                    if file == "README.md":
+                        continue
+
+                    file_path = os.path.join(root, file)
 
-                # Skip files that don't have a title.
-                if not title:
-                    continue
+                    try:
+                        # Read the file so I can get the header, which contains the title
+                        with open(os.path.join(root, file), "r") as file_obj:
+                            title = file_obj.readline().replace("#", "").strip()
 
-                # Skip the README file.
-                if file == "README.md":
-                    continue
+                        # Skip files that don't have a title
+                        if not title:
+                            continue
 
-                file_path = os.path.join(root, file)
-                relative_path = os.path.relpath(file_path, directory)
-                contents.append(f"- [{title}]({relative_path})")
+                        relative_path = os.path.relpath(file_path, directory)
+                        contents.append(f"- [{title}]({relative_path})")
+                    except Exception as e:
+                        click.echo(f"Warning: Could not process file {file}: {e}")
 
-            sorted_contents = sorted(contents)
-            f.write("\n".join(sorted_contents))
+                sorted_contents = sorted(contents)
+                f.write("\n".join(sorted_contents))
 
     click.echo(f"README file generated at {readme_file}")
 
 
 if __name__ == "__main__":
-    generate_readme_links()
+    generate_readme_links()