Sure

palewire · Aug 13, 2023 · 4218cb6 · 4218cb6
1 parent b2bd5da
commit 4218cb6
Show file tree

Hide file tree

Showing 43 changed files with 72 additions and 64 deletions.
diff --git a/.DS_Store b/.DS_Store
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,5 @@
+docs/html
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

diff --git a/Makefile b/Makefile
@@ -72,6 +72,11 @@ all:  # Start the test server
 	@cd docs && $(PIPENV) make livehtml
 
 
+serve:  # Start the test server
+	$(call banner,    🏗️ Building site 🏗️)
+	$(PIPENV) sphinx-autobuild -b html docs docs/html
+
+
 help: ## Show this help. Example: make help
 	@egrep -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
 

diff --git a/Pipfile b/Pipfile
@@ -7,7 +7,6 @@ name = "pypi"
 sphinx = "*"
 sphinx-autobuild = "*"
 myst-parser = "*"
-sphinx-multitoc-numbering = "*"
 
 [dev-packages]
 

diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/_static/.DS_Store b/docs/_static/.DS_Store
diff --git a/docs/_static/img/.DS_Store b/docs/_static/img/.DS_Store
diff --git a/docs/_static/img/actions.png b/docs/_static/img/actions.png
diff --git a/docs/_static/img/admin-pr.png b/docs/_static/img/admin-pr.png
diff --git a/docs/_static/img/blank-pr.png b/docs/_static/img/blank-pr.png
diff --git a/docs/_static/img/contribution-story.png b/docs/_static/img/contribution-story.png
diff --git a/docs/_static/img/contribution.png b/docs/_static/img/contribution.png
diff --git a/docs/_static/img/data-dir.png b/docs/_static/img/data-dir.png
diff --git a/docs/_static/img/draft.png b/docs/_static/img/draft.png
diff --git a/docs/_static/img/editor.png b/docs/_static/img/editor.png
diff --git a/docs/_static/img/example-word.png b/docs/_static/img/example-word.png
diff --git a/docs/_static/img/fork-popup.png b/docs/_static/img/fork-popup.png
diff --git a/docs/_static/img/fork.png b/docs/_static/img/fork.png
diff --git a/docs/_static/img/go-to-repo.png b/docs/_static/img/go-to-repo.png
diff --git a/docs/_static/img/issue-tracker.png b/docs/_static/img/issue-tracker.png
diff --git a/docs/_static/img/issue.png b/docs/_static/img/issue.png
diff --git a/docs/_static/img/merged.png b/docs/_static/img/merged.png
diff --git a/docs/_static/img/moneyinpolitics-repo.png b/docs/_static/img/moneyinpolitics-repo.png
diff --git a/docs/_static/img/moneyinpolitics-site.png b/docs/_static/img/moneyinpolitics-site.png
diff --git a/docs/_static/img/name-fork.png b/docs/_static/img/name-fork.png
diff --git a/docs/_static/img/pencil.png b/docs/_static/img/pencil.png
diff --git a/docs/_static/img/pr.png b/docs/_static/img/pr.png
diff --git a/docs/_static/img/source-control.png b/docs/_static/img/source-control.png
diff --git a/docs/_static/img/success.png b/docs/_static/img/success.png
diff --git a/docs/_static/img/switch-fork.png b/docs/_static/img/switch-fork.png
diff --git a/docs/actions.md b/docs/actions.md
@@ -3,12 +3,12 @@
 
 # Actions
 
-Once your commit is merged into the original repository, that will trigger an update to the cummings.ee website via GitHub Actions.
+Once your commit is merged into the original repository, that will trigger an update to the moneyinpolitics.wtf website via GitHub Actions.
 
 With GitHub Actions, users can create custom, automated steps in their workflow that can be triggered by specific events, such as when a code change is pushed to a repository or when a pull request is opened. This allows developers to automate tasks such as building and testing their code, deploying their applications, and running other processes related to their projects. 
 
 You can see a repository's workflows by clicking the Actions tab in the middle of the page. There you'll find a list of the latest events.
 
 ![GitHub Actions](_static/img/actions.png)
 
-In this case, you should see that a build routine triggered by your pull request has finished successfully. That means we should expect to see your poem live on the website.
+In this case, you should see that a build routine triggered by your pull request has finished successfully. That means we should expect to see your example live on the website.
diff --git a/docs/commits.md b/docs/commits.md
@@ -18,14 +18,14 @@ In the form that appears, your should enter a brief message into the text input
 In the case of this example, a reasonable commit message could read:
 
 ```
-Transcription of "if being morticed with a dream." Fixes #179
+Added example of "contribution" in use. Fixes #127
 ```
 
-Draft something similar, customized to fit your poem and issue number. Then enter it into the form's box and press the green "Commit & Push" button below. You should see a popup box.
+Draft something similar, customized to fit your definition and issue number. Then enter it into the form's box and press the green "Commit & Push" button below. You should see a popup box.
 
 ![Fork popup](_static/img/fork-popup.png)
 
-Because you are not an owner of the cummings.ee repository, you do not have permission to save your commits without the approval of the project's maintainers. That's where GitHub's forking system comes in. Click the green "Fork respository" button.
+Because you are not an owner of the moneyinpolitics.wtf repository, you do not have permission to save your commits without the approval of the project's maintainers. That's where GitHub's forking system comes in. Click the green "Fork respository" button.
 
 A small box will appear asking you to enter a name. Accept the default value, which should be something like `patch-1`.
 
@@ -36,3 +36,5 @@ Finally, it will ask you if you want to "switch" to your forked repository. Hit
 ![Switching to fork](_static/img/switch-fork.png)
 
 Once the page reloads, you should hit the menu button in the upper left and select the "Go to repository" option at the bottom of the pulldown.
+
+![Go to repository](_static/img/go-to-repo.png)
diff --git a/docs/conf.py b/docs/conf.py
@@ -10,12 +10,11 @@
 
 extensions = [
     "myst_parser",
-    "sphinx_multitoc_numbering",
 ]
 templates_path = ["_templates"]
 source_suffix = ".rst"
 master_doc = "index"
-html_extra_path = ["_extra"]
+html_extra_path = []
 
 project = "First Pull Request"
 year = datetime.now().year

diff --git a/docs/edits.md b/docs/edits.md
@@ -3,31 +3,38 @@
 
 # Edits
 
-When you arrive on the YAML page, you should see that the `text` attribute we saw earlier is absent. That confirms that the poem has yet to be transcribed.
+When you arrive on the YAML page, you should see that the `is_use` attribute on the first defintion contains only a single entry.
 
-![A cummings.ee poem YAML file](_static/img/no-edits.png)
+!["contribution"](_static/img/example-word.png)
 
 To begin editing, click the down arrow next to the pencil-shaped icon at the upper right of the file. Select "open in github.dev" from the pulldown menu that appears.
 
 ![The GitHub pencil button pulldown](_static/img/pencil.png)
 
-That will open a new panel where you are free to start editing the code in GitHub's web editor, which allows you to make revisions from your web browser.
+That will open a new panel where you are free to start revising the repository's code in GitHub's web editor, which allows you to work from your web browser.
 
 ![github.dev's web editing panel](_static/img/editor.png)
 
-Paste the following YAML into the bottom of the file, which will create the `text` entry where you can transcribe the poem.
-
-```yaml
-text: |-1
- put your first line here
+```{note}
+ While most computer programmers prefer to download the repository's source code and use a text editor installed on their own computer, GitHub's web editor is a great way to experiment and get started.
 ```
 
-This is how cummings.ee has chosen to take advantage of YAML's method for handling strings of text that run over multiple lines. Note that the first line of the poem, which you should customize to match your verse, is indented by a single space. That is intended to match the `-1` configuration option we've passed in the line above. All subsequent lines should also be prefixed with a single space.
+Visit [Google News](https://news.google.com/) and search for the definition you are editing. Look for examples of the word used by a reputable media organization in a way that fits the definition.
+
+In our demonstration case, we are editing the word "contribution." I found an example in [a story](https://www.reuters.com/legal/fugees-star-says-money-malaysian-financier-was-obama-photo-not-campaign-donation-2023-04-19/) published by Reuters, the world's largest independent news organization.
+
+[![A screenshot of the Reuters story](_static/img/contribution-story.png)](https://www.reuters.com/legal/fugees-star-says-money-malaysian-financier-was-obama-photo-not-campaign-donation-2023-04-19/)
 
-Now refer to the first edition of the poem [found on archive.org](https://archive.org/details/is-5-ee-cummings/page/n101/mode/2up). 
+When you find an example for your definition, you should create a new YAML item. It should contain a `text` attribute with the sentence containing the word, the name of the `source` publication and a `url` attribute with the link to the story.
+
+```yaml
+- text: "It is illegal for foreigners to donate to U.S. election campaigns, and it is also against the law to pay someone else to make a campaign contribution."
+  source: Reuters
+  url: https://www.reuters.com/legal/fugees-star-says-money-malaysian-financier-was-obama-photo-not-campaign-donation-2023-04-19/
+```
 
-![The first edition](_static/img/first-edition.png)
+That code snippet should be added to the `definition_list` attribute, which is a list of all the definitions for the word. It will need to be indented six spaces to be nested under the `definition_list` entry you're illustrating.
 
-And enter the text exactly as it appears on the page into your YAML file.
+![Draft example](_static/img/draft.png)
 
-![An entered poem](_static/img/entered.png)
+It's important to indent the properly. The code will not work if it is not indented correctly. Take a look at the other definitions in the file to see how they are nested and try to match that.
diff --git a/docs/end.md b/docs/end.md
@@ -3,12 +3,10 @@
 
 # The end
 
-Visit [cummings.ee](https://cummings.ee) in your browser and navigate to the “is 5” page.
+Visit [moneyinpolitics.wtf](https://moneyinpolitics.wtf) in your browser and navigate to the page for your definition.
 
-[![“is 5”](_static/img/is-5.png)](https://cummings.ee/book/is-5/)
+You should now see that the entry now includes your example.
 
-You should now see that the title of your poem includes a hyperlink. Click it. You should see the poem you transcribed published on the web.
-
-[![success](_static/img/success.png)](https://cummings.ee/book/is-5/poem/four-ii/)
+[![success](_static/img/success.png)](https://moneyinpolitics.wtf/contribution/)
 
 Congratulations. You've completed your first pull request.
diff --git a/docs/forks.md b/docs/forks.md
@@ -7,7 +7,7 @@ A fork is a copy of a repository that belongs to someone else. When you fork a r
 
 You can change your fork without affecting the original. This is useful if you want to suggest changes to a project when you don't have permission to edit the source.
 
-You are now looking at your fork of the original cummings.ee repository. The only difference is the commit you just made, adding a new poem to the YAML directory for “is 5.”
+You are now looking at your fork of the original moneyinpolitics.wtf repository. The only difference is the commit you just made, adding a new example to a dictionary entry.
 
 ![Fork](_static/img/fork.png)
 

diff --git a/docs/framework.md b/docs/framework.md
@@ -1,28 +1,28 @@
 ```{include} _templates/nav.html
 ```
 
-## The framework
+# The framework
 
-When you land on [github.com/palewire/cummings.ee](https://github.com/palewire/cummings.ee), you'll see that the repository is already populated with an array of folders and files. This is the code that powers [cummings.ee](https://cummings.ee/) by providing the HTML layout, its cosmetic style and, most important, its content.
+When you land on [github.com/palewire/moneyinpolitics.wtf](https://github.com/palewire/moneyinpolitics.wtf), you'll see that the repository is already populated with an array of folders and files. This is the code that powers [moneyinpolitics.wtf](https://moneyinpolitics.wtf) by providing the HTML layout, its cosmetic style and, most important, its content.
 
-[![github.com/palewire/cummings.ee](_static/img/cummings-repo.png)](https://github.com/palewire/cummings.ee)
+[![github.com/palewire/moneyinpolitics.wtf](_static/img/moneyinpolitics-repo.png)](https://github.com/palewire/moneyinpolitics.wtf)
 
-Everything is arranged according to the specifications of the “framework” employed by the site's creators. What's a framework? Nothing more than fancy name for a set of software tools designed to work together. It can take dozens of different tricks to assemble a website. Frameworks aim to make the challenge easier by curating an array of tools into a simplified arrangement that saves time, like a tool belt.
+Everything is arranged according to the specifications of the “framework” employed by the site's creators. What's a framework? Nothing more than fancy name for a set of software tools designed to work together. It can take dozens of different tricks to assemble a website. Frameworks aim to make the challenge easier by curating an array of tools into a practical arrangement, like a tool belt.
 
-Some frameworks are more popular than others. The programming languages and the details vary, but the fundamentals are almost all the same. Other examples include [Django](https://en.wikipedia.org/wiki/Django_(web_framework)) or [Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails) or [React](https://en.wikipedia.org/wiki/React_(JavaScript_library)).
+Some frameworks are more popular than others. Other examples include [Django](https://en.wikipedia.org/wiki/Django_(web_framework)) or [Rails](https://en.wikipedia.org/wiki/Ruby_on_Rails) or [React](https://en.wikipedia.org/wiki/React_(JavaScript_library)). While the programming languages and the details vary, the fundamentals are almost all the same.
 
-[![github.com/datadesk/baker](_static/img/baker-repo.png)](https://github.com/datadesk/baker)
+The moneyinpolitics.wtf repository is an example of a site built with [baker](https://github.com/datadesk/baker), a framework invented at the Los Angeles Times. It’s also used in the ProPublica, THE CITY and The Baltimore Banner newsrooms, among others. Like moneyinpolitics.wtf, baker is freely available on GitHub at [github.com/datadesk/baker](https://github.com/datadesk/baker).
 
-The cummings.ee repository is an example of a site built with [baker](https://github.com/datadesk/baker), a framework invented at the Los Angeles Times. It’s also used by ProPublica, THE CITY and The Baltimore Banner, among others. Like cummings.ee, baker is freely available on GitHub at [github.com/datadesk/baker](https://github.com/datadesk/baker).
+[![github.com/datadesk/baker](_static/img/baker-repo.png)](https://github.com/datadesk/baker)
 
 Baker is what is known as a static-site framework. Static-site frameworks allow you to build websites using only flat files, such as HTML, CSS, and JavaScript. Unlike a traditional “dynamic” website, which relies on a server-side language like PHP or Ruby to generate content on the fly, a static site is pre-generated and served as-is to the user. This has several benefits, including faster load times, better security and simpler deployment. Some other examples of static site frameworks are [Jekyll](https://en.wikipedia.org/wiki/Jekyll), [Gatsby](https://en.wikipedia.org/wiki/Gatsby_(JavaScript_framework)) and [Hugo](https://gohugo.io/).
 
-[![“First Visual Story”](_static/img/first-visual-story.png)](https://palewi.re/docs/first-visual-story/)
-
 This class will not cover how to build a website with baker. If you're interested in that, you should explore [“First Visual Story,”](https://palewi.re/docs/first-visual-story/) a separate tutorial that will guide you through every step of the process.
 
-Today you will only need to navigate to the folder where poems are transcribed. We will be adding works drawn from [“is 5,”](https://cummings.ee/book/is-5/) a book of verse that was first published by Boni & Liveright in 1926. Due to the way U.S. copyright works, it entered the public domain on January 1, 2022, allowing anyone to legally republish and build off the intellectual property.
+[![“First Visual Story”](_static/img/first-visual-story.png)](https://palewi.re/docs/first-visual-story/)
+
+Today you will only need to navigate to the folder where entries in the dictionary are defined. Our goal is to add examples of campaign finance jargon in use, so that readers can better understand the terms. To do that, we will need to edit the files in the `_data/dictionary` folder.
 
-[![“is 5” on cummings.ee](_static/img/is-5.png)](https://cummings.ee/book/is-5/)
+[![The dictionary directory](_static/img/data-dir.png)](https://github.com/palewire/moneyinpolitics.wtf/tree/main/_data/dictionary)
 
-At the time of this writing, only a fraction of the book's poems have been entered into the site. Due to the way baker has been configured, the files for the book can be found in the repository's `_data/poems/is-5` folder. You should navigate there by clicking into the folders in GitHub interface or by going directly to [this URL](https://github.com/palewire/cummings.ee/tree/master/_data/poems/is-5).
+You should navigate there by clicking into the folders in GitHub interface or by going directly to [this URL](https://github.com/palewire/moneyinpolitics.wtf/tree/main/_data/dictionary).
diff --git a/docs/issues.md b/docs/issues.md
@@ -5,14 +5,14 @@
 
 GitHub’s issue tracker is a way to track tasks, enhancements and bugs. Each issue has its own page where you can provide details about the problem or idea, and where others can contribute to the discussion. You can use labels and milestones to organize your issues and track their progress.
 
-Every repository has its own tracker, which you can find by clicking the "Issues" tab in the upper left. In our case, it will take you to [github.com/palewire/cummings.ee/issues](https://github.com/palewire/cummings.ee/issues). If you're interested in contributing to an open-source project, you should review the issue tracker before you dive into the code. You can find ideas for where help is needed and see if the work you're interested in has already been discussed.
+Every repository has its own tracker, which you can find by clicking the "Issues" tab in the upper left. In our case, it will take you to [github.com/palewire/moneyinpolitics.wtf/issues](https://github.com/palewire/moneyinpolitics.wtf/issues). If you're interested in contributing to an open-source project, you should review the issue tracker before you dive into the code. You can find ideas for where help is needed and see if the work you're interested in has already been discussed.
 
-As of this writing, you should seen several dozen issues asking contributors to enter poems. Click on a title that interests you.
+As of this writing, you should see more than a dozen issues asking contributors to find and enter examples of words in use. Click on one that interests you.
 
-[![cummings.ee issue tracker](_static/img/issue-tracker.png)](https://github.com/palewire/cummings.ee/issues)
+[![moneyinpolitics.wtf issue tracker](_static/img/issue-tracker.png)](https://github.com/palewire/moneyinpolitics.wtf/issues)
 
-There you will find a comment with two links. One to poem's YAML file. Another to a digital scan of the page in a first edition of "is 5" where the poem was originally published.
+In whatever ticket you choose you will find a comment with a link to the definition's YAML file. For the purposes of this demontration, I am going to choose the ticket for "contribution." 
 
-[![cummings.ee issue](_static/img/issue.png)](https://github.com/palewire/cummings.ee/issues/179)
+[![moneyinpolitics.wtf issue](_static/img/issue.png)](https://github.com/palewire/moneyinpolitics.wtf/issues/127)
 
-Open the two links in separate browser tabs.
+To claim the issue, leave a comment saying you're working on it. This will signal to others that you're already addressing the task. Then click the link to the YAML file to open it on GitHub.
diff --git a/docs/merges.md b/docs/merges.md
@@ -19,7 +19,7 @@ GitHub has several code review features that are available in a pull request. Th
 * Threaded conversations: These allow reviewers and contributors to have a back-and-forth discussion about the changes being proposed, without cluttering up the pull request with long lists of comments.
 * Change requests: This allows reviewers to ask the person who created the pull request to make specific changes to the code, before the pull request is merged.
 
-In the case of this project, the maintainer's chief responsibility is to verify that the YAML is properly formatted and to compare the quality of the transcription against the source materials. Once those hurdles have been cleared, the pull request can be merged in by pressing the green "Merge pull request" button.
+In the case of this project, the maintainer's chief responsibility is to verify that the YAML is properly formatted and to vet the quality of the example for the definition. Once those hurdles have been cleared, the pull request can be merged in by pressing the green "Merge pull request" button.
 
 ![A merged pull request](_static/img/merged.png)
 

diff --git a/docs/mission.md b/docs/mission.md
@@ -7,7 +7,6 @@ If you complete this class, you will gain a basic understanding of how to submit
 
 You will explore a code repository, make edits to the source and then propose your changes be included in the original project. This pattern, known as a [pull request](https://docs.github.com/en/pull-requests), is fundamental to the process that allows developers around the world to collaborate. 
 
-[![cummings.ee](_static/img/cummings-archive.png)](https://cummings.ee)
+[![moneyinpolitics.wtf](_static/img/moneyinpolitics-site.png)](https://moneyinpolitics.wtf)
 
-As part of the practice, you will make a real contribution to [cummings.ee](https://cummings.ee), the in-progress, crowdsourced effort to transcribe the poetry of [Edward Estlin Cummings](https://en.wikipedia.org/wiki/E._E._Cummings).
-
+As part of the practice, you will make a real contribution to [moneyinpolitics.wtf](https://moneyinpolitics.wtf), the in-progress, crowdsourced effort to create America's most comprehensive dictionary of campaign finance jargon.