Merge pull request #15 from williln/subdir-toc

Add READMEs with clickable tables of contents to internal subdirs

.github/workflows/build.yml

@@ -29,15 +29,40 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements.txt
       - name: Build database
-        run: python build_database.py
+        run: python scripts/build_database.py
       - name: Update README
         run: |-
-          python update_readme.py --rewrite
+          python scripts/update_readme.py --rewrite
           cat README.md
-      - name: Commit and push if README changed
+      - name: Update subdir README's 
+        run: |-
+          python3 scripts/build_subdir_toc.py aws
+          python3 scripts/build_subdir_toc.py celery
+          python3 scripts/build_subdir_toc.py django
+          python3 scripts/build_subdir_toc.py django-rest-framework
+          python3 scripts/build_subdir_toc.py drf-yasg
+          python3 scripts/build_subdir_toc.py fast-ai
+          python3 scripts/build_subdir_toc.py git
+          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 htmx
+          python3 scripts/build_subdir_toc.py javascript
+          python3 scripts/build_subdir_toc.py kubernetes
+          python3 scripts/build_subdir_toc.py mac
+          python3 scripts/build_subdir_toc.py markdown
+          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 pytest
+          python3 scripts/build_subdir_toc.py python
+          python3 scripts/build_subdir_toc.py r
+          python3 scripts/build_subdir_toc.py slack
+          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 README")
+          git diff --quiet || (git add README.md && git commit -m "Updated READMEs")
           git push

aws/README.md

@@ -0,0 +1,3 @@
+# aws
+
+- [AWS S3 and Boto3 Cheat Sheet](s3_and_boto_and_minio.md)

celery/README.md

@@ -0,0 +1,3 @@
+# celery
+
+- [Scheduling a nightly Celery task with Celery Beat](schedule_nightly_task.md)

django-rest-framework/README.md

@@ -0,0 +1,4 @@
+# django-rest-framework
+
+- [Adding a custom pagination class to an action](custom_action_pagination.md)
+- [Passing extra info in `context` to your DRF serializer](pass_to_context.md)

django/README.md

@@ -0,0 +1,25 @@
+# django
+
+- [Adding a custom context processor to your Django app so you can include bits of data in your template headers more easily](add_context_processor.md)
+- [Adding a custom field to the Django admin list display](custom_fields.md)
+- [Adding a custom tag with `django-taggit`](django-taggit-custom-tag.md)
+- [Adding ability to search in the Django Admin](add_search.md)
+- [Adding extra fields to the list view in the Django Admin](add_fields_to_list_view.md)
+- [Adding filtering functionality to the Django Admin](add_filtering.md)
+- [Caching in Django Projects](caching.md)
+- [Finding out how many objects have N connections to the other model in a M2M relationship](m2m_queries_how_many_objects_have_no_connections.md)
+- [Finding the longest value of a particular field](longest_value_in_field.md)
+- [Handling 404 Responses in Django](404_handling.md)
+- [How I added a very simple django-streamfield example to a project](how_I_added_django_streamfield.md)
+- [How I set up `django-activity-stream`, including a simple test](how_i_added_django_activity_stream_with_test.md)
+- [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)
+- [Testing Django signals, and disabling signals in tests (Django 2.2)](testing_django_signals.md)
+- [Using Django Aggregation](aggregation.md)
+- [Using Enums in a Django Model ChoiceField (Django 2.2)](enums_as_choices.md)
+- [Using `Coalesce` to provide a default value for `aggregate` queries](aggregation_coalesce.md)
+- [Using `defer()` to limit the data you get from your models](defer.md)
+- [Using `django-countries`](django_countries.md)
+- [Using inline formsets with `inlineformset_factory`](using_inline_formsets.md)
+- [Why won't my Django file URLs come back signed from S3?](aws_signed_urls.md)

drf-yasg/README.md

@@ -0,0 +1,5 @@
+# drf-yasg
+
+- [How to document your query parameters for `drf_yasg`](query_params.md)
+- [How to properly serialize a `serializer_method_field` with `drf_yasg`](serializer_method_field.md)
+- [How to serialize your request parameters for POST/PUT/PATCH requests](define_request_body.md)

fast-ai/README.md

@@ -0,0 +1,3 @@
+# fast-ai
+
+- [Converting a `fastcore.basics.AttrDict` into a regular dictionary.](obj2dict.md)

git/README.md

@@ -0,0 +1,3 @@
+# git
+
+- [Moving from an old repo to a new repo in another organization](moving_to_a_new_repo.md)

github/README.md

@@ -0,0 +1,11 @@
+# github
+
+- [Commenting on an issue from a GitHub Action](gh-actions-comment-issue.md)
+- [Creating a new file and committing it using a GitHub Action](gh-actions-step-to-create-and-commt-a-file.md)
+- [Github Action that leaves a comment on new PRs or issues](action_pr_comment.md)
+- [How to use a Github Action](howto_github_action.md)
+- [Making one job in a workflow depend on another job](gh-actions-set-job-dependency.md)
+- [Parsing JSON output from a GitHub Issue template in a GitHub Action](gh-actions-parse-json.md)
+- [Running an action conditionally](gh-action-run-job-conditionally.md)
+- [Setting output for a step in a job, so a different job can use it](gh-action-set-output.md)
+- [Temporarily disabling a GitHub action without touching the workflow file](gh_actions_temporary_disable.md)

google/README.md

@@ -0,0 +1,3 @@
+# google
+
+- [Using Google Cloud Service Accounts and authenticating as a dictionary (without the json file) in a Django project](using_service_account_as_dict.md)

home-office/README.md

@@ -0,0 +1,3 @@
+# home-office
+
+- [Troubleshooting my Brother HL-2270DW Wireless Printer](printer.md)

htmx/README.md

@@ -0,0 +1,4 @@
+# htmx
+
+- [Making a simple `hx-get` request](making_an_hxget_request.md)
+- [Updating other elements on the page with `hx-swap-oob`](out_of_band_swaps.md)

javascript/README.md

@@ -0,0 +1,3 @@
+# javascript
+
+- [TimelineJS for building interactive timelines from spreadsheet or JSON](timelinejs.md)

justfile

@@ -0,0 +1,28 @@
+# Define default recipe for ease of use
+default:
+    @echo "Specify a command to run. Options include: up, down, kill, bash, test, migrate."
+
+build-internal-readmes:
+    python3 scripts/build_subdir_toc.py aws
+    python3 scripts/build_subdir_toc.py celery
+    python3 scripts/build_subdir_toc.py django
+    python3 scripts/build_subdir_toc.py django-rest-framework
+    python3 scripts/build_subdir_toc.py drf-yasg
+    python3 scripts/build_subdir_toc.py fast-ai
+    python3 scripts/build_subdir_toc.py git
+    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 htmx
+    python3 scripts/build_subdir_toc.py javascript
+    python3 scripts/build_subdir_toc.py kubernetes
+    python3 scripts/build_subdir_toc.py mac
+    python3 scripts/build_subdir_toc.py markdown
+    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 pytest
+    python3 scripts/build_subdir_toc.py python
+    python3 scripts/build_subdir_toc.py r
+    python3 scripts/build_subdir_toc.py slack
+    python3 scripts/build_subdir_toc.py wagtail

kubernetes/README.md

@@ -0,0 +1,4 @@
+# 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)

mac/README.md

@@ -0,0 +1,3 @@
+# mac
+
+- [Control when your laptop locks, turns off the display, etc.](control_when_machine_locks.md)

markdown/README.md

@@ -0,0 +1,3 @@
+# markdown
+
+- [Making a collapsible markdown section](collapsible_markdown.md)

meilisearch/README.md

@@ -0,0 +1,5 @@
+# meilisearch
+
+- [Securing Meilisearch with Docker for local Django development](securing_meilisearch_in_docker.md)
+- [Securing the Meilisearch search itself](securing_meilisearch_search.md)
+- [Setting up Meilisearch with Python, Docker, and Compose for local development](setting_up_meilisearch_python_docker.md)

microsoft-dynamics/README.md

@@ -0,0 +1,3 @@
+# microsoft-dynamics
+
+- [About Microsoft Dynamics](about-microsoft-dynamics.md)

misc/README.md

@@ -0,0 +1,3 @@
+# misc
+
+- [Relume Design League - competitive web design](competitive_web_design.md)

pytest/README.md

@@ -0,0 +1,3 @@
+# pytest
+
+- [Test that an exception is raised](assert_raises.md)

python/README.md

@@ -0,0 +1,7 @@
+# python
+
+- [ChatGPT-4 distills the Python `mailbox` docs for me.](mailbox.md)
+- [Create a new Python virtual environment](new-virtualenv.md)
+- [Generate a markdown file with a table of contents in Python](generate-toc.md)
+- [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)

r/README.md

@@ -0,0 +1,4 @@
+# r
+
+- [How to convert an `.rda` file to JSON](convert_rda_to_json.md)
+- [`taylor`: The Taylor Swift / R Project](taylor_swift.md)

scripts/build_subdir_toc.py

@@ -0,0 +1,44 @@
+import os
+
+import click
+
+
+@click.command()
+@click.argument("directory", type=click.Path(exists=True))
+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()
+
+                # 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})")
+
+            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()

slack/README.md

@@ -0,0 +1,3 @@
+# slack
+
+- [Keep Slack from kicking you out of huddles when your machine locks](computer_locking_kicks_out_of_huddles.md)

wagtail/README.md

@@ -0,0 +1,12 @@
+# wagtail
+
+- [Add Wagtail to an existing Django project](add_to_existing_project.md)
+- [Cheat Sheet for Wagtail StreamField](cheat_sheet_wagtail_streamfield.md)
+- [Cheat Sheet: Wagtail Page Model Fields](cheat_sheet_wagtail_page_model_fields.md)
+- [Choosing Between Wagtail Page Models and Django Models](choosing_wagtail_page_models_vs_django_models.md)
+- [Create a Custom Nested Block for Wagtail StreamField](create_custom_nested_block_for_streamfield.md)
+- [Creating Custom StreamField Blocks](create_custom_streamfield_block.md)
+- [Creating Wagtail pages with Streamfield content programmatically](creating_streamfield_content_programmatically.md)
+- [Example of linking Django models to Wagtail Page models](example_integrating_wagtail_page_models_into_django_models.md)
+- [Seeding my Wagtail site](seeding_wagtail_site.md)
+- [What to do if you delete the default Wagtail homepage](fix_deleted_root_page.md)