docs: Remove old docs, format docs

.mdformat.toml

@@ -0,0 +1,8 @@
+# Wrap lines to 80 characters.
+wrap = 80
+
+# Apply consecutive numbering to ordered lists.
+number = true
+
+# Use the line feed (AKA newline or \n) character for line endings.
+end_of_line = "lf"

Pipfile

@@ -4,19 +4,20 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
+boto3 = "1.*"
 flask = "==3.*"
-boto3 = "*"
 
 [dev-packages]
 black = "==24.*"
-pylint = "==3.*"
+boto3-stubs = {extras = ["essential"], version = "1.*"}
+coverage = "==7.*"
+invoke = "==2.*"
+mdformat = "0.*"
 mypy = "==1.*"
+pylint = "==3.*"
 pytest = "==8.*"
-invoke = "==2.*"
-coverage = "==7.*"
 python-dotenv = "==1.*"
-sqlfluff = "*"
-boto3-stubs = {extras = ["essential"], version = "*"}
+sqlfluff = "3.*"
 
 [requires]
 python_version = "3.12"

README.md

@@ -3,6 +3,6 @@
 [![CI](https://github.com/clingen/stanford-affils/actions/workflows/check.yml/badge.svg)](https://github.com/ClinGen/stanford-affils/actions)
 [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/8941/badge)](https://www.bestpractices.dev/projects/8941)
 
-affils is Stanford ClinGen's affiliations service. It is under
-development. See our [roadmap](https://github.com/ClinGen/affils/issues/1)
-and our [documentation](./doc/README.md).
+affils is Stanford ClinGen's affiliations service. It is under development. See
+our [roadmap](https://github.com/ClinGen/affils/issues/1) and our
+[documentation](./doc/README.md).

doc/README.md

@@ -4,36 +4,26 @@ This is the documentation for the affiliations service. We follow the
 [Divio documentation organization system](https://documentation.divio.com/introduction.html).
 
 - [Tutorials](./tutorial.md) (learning-oriented)
-    - Tutorials are lessons that take the reader by the hand through a series of
-      steps to complete a project of some kind. Unlike how-to guides, tutorials
-      don't assume lots of prerequisite knowledge.
-    - [Get started](./tutorial.md#get-started)
+  - Tutorials are lessons that take the reader by the hand through a series of
+    steps to complete a project of some kind. Unlike how-to guides, tutorials
+    don't assume lots of prerequisite knowledge.
+  - [Get started](./tutorial.md#get-started)
 - [How-to guides](./howto.md) (problem-oriented)
-    - How-to guides take the reader through the steps required to solve a
-      real-world problem. They are recipes, directions to achieve a specific
-      end. Unlike tutorials, they typically assume a fair amount of prerequisite
-      knowledge.
-    - [Run code checks](./howto.md#run-code-checks)
-    - [Organize imports and constants](./howto.md#organize-imports-and-constants)
-    - [Write a TODO comment](./howto.md#write-a-todo-comment)
-    - [Write a commit message](./howto.md#write-a-commit-message)
-    - [Set up Postgres locally](./howto.md#set-up-postgres-locally)
-    - [View info on AWS](./howto.md#view-info-on-aws)
-    - [View logs on AWS](./howto.md#view-logs-on-aws)
-    - [Deploy to AWS](./howto.md#deploy-to-aws)
+  - How-to guides take the reader through the steps required to solve a
+    real-world problem. They are recipes, directions to achieve a specific end.
+    Unlike tutorials, they typically assume a fair amount of prerequisite
+    knowledge.
+  - [Run code checks](./howto.md#run-code-checks)
+  - [Organize imports and constants](./howto.md#organize-imports-and-constants)
+  - [Write a TODO comment](./howto.md#write-a-todo-comment)
+  - [Write a commit message](./howto.md#write-a-commit-message)
 - [Explanations](./explanation.md) (understanding-oriented)
-    - Explanation, or discussions, clarify and illuminate a particular topic.
-      They broaden the documentation’s coverage of a topic. Explanations can
-      equally well be described as discussions; they are discursive in nature.
-      They are a chance for the documentation to relax and step back from the
-      software, taking a wider view, illuminating it from a higher level or even
-      from different perspectives. You might imagine a discussion document being
-      read at leisure, rather than over the code.
-    - [Affiliations workflow diagrams](./explanation.md#affiliations-workflow-diagrams)
-    - [Environment variables](./explanation.md#environment-variables)
-- [Reference guides](./reference.md) (information-oriented)
-    - Reference guides are technical descriptions of the machinery and how to
-      operate it. Reference guides have one job only: to describe. They are
-      code-determined, because ultimately that’s what they describe: key
-      classes, functions, APIs, and so they should list things like functions,
-      fields, attributes and methods, and set out how to use them.
+  - Explanation, or discussions, clarify and illuminate a particular topic. They
+    broaden the documentation’s coverage of a topic. Explanations can equally
+    well be described as discussions; they are discursive in nature. They are a
+    chance for the documentation to relax and step back from the software,
+    taking a wider view, illuminating it from a higher level or even from
+    different perspectives. You might imagine a discussion document being read
+    at leisure, rather than over the code.
+  - [Affiliations workflow diagrams](./explanation.md#affiliations-workflow-diagrams)
+  - [Environment variables](./explanation.md#environment-variables)

doc/explanation.md

@@ -2,18 +2,14 @@
 
 ## Affiliations workflow diagrams
 
-We have diagrams for our current and desired affiliations workflow in
-the [diagrams directory](./diagrams).
+We have diagrams for our current and desired affiliations workflow in the
+[diagrams directory](./diagrams).
 
 ## Environment variables
 
-There's a `.env.template` file that is the source of truth for
-environment variable keys. You're supposed to create a `.env.local` file
-and a `.env.prod` file based on `.env.template`. The keys in each
-environment variable file should stay the same at all times. This is
-enforced programmatically using Invoke tasks. (See the `tasks.py` file
-for more details on this.) The values of the keys can differ between
-files, of course.
-
-When you deploy to production, the production environment variables are
-automatically uploaded to production.
+There's a `.env.template` file that is the source of truth for environment
+variable keys. You're supposed to create a `.env` file file based on
+`.env.template`. The keys in each environment variable file should stay the same
+at all times. This is enforced programmatically using Invoke tasks. (See the
+`tasks.py` file for more details on this.) The values of the keys can differ
+between files, of course.

doc/howto.md

@@ -17,36 +17,33 @@ inv check
 
 ## Style your code
 
-Defer to the formatter (Black) and the linter (pylint). If neither of
-them have an opinion, refer to
+Defer to the formatter (Black) and the linter (pylint). If neither of them have
+an opinion, refer to
 [Google's Python style guide](https://google.github.io/styleguide/pyguide.html).
 
 ## Write code that can be submitted to the main branch
 
 - Must pass the `check` script.
 - New code must have automated tests.
 - New code must have docstrings.
-- If adding a new tool or something that other developers need to
-  understand, there must be a tutorial for it.
-- If a manual process is being added, there must be a how-to guide for
-  it.
-- If changing something significant (e.g. architecture) there should be
-  a written explanation.
-- If doing something complex or weird, there should be an explanation
-  for it.
+- If adding a new tool or something that other developers need to understand,
+  there must be a tutorial for it.
+- If a manual process is being added, there must be a how-to guide for it.
+- If changing something significant (e.g. architecture) there should be a
+  written explanation.
+- If doing something complex or weird, there should be an explanation for it.
 
 ## Conform to best practices
 
 See our Gecko Group developer best practices spreadsheet
 [here](https://docs.google.com/spreadsheets/d/1MLeEQE-v3eEnEtKNG4oJ8q6a8pal9q462TTgVcodcg4/edit?pli=1#gid=0).
 We are also working toward conforming to OpenSSF Best Practices. See
-[this page](https://www.bestpractices.dev/en/projects/8941) for more
-info.
+[this page](https://www.bestpractices.dev/en/projects/8941) for more info.
 
 ## Organize imports and constants
 
-At the top of any given module there will probably be imports and
-constants. Our preferred way of organizing them is as follows:
+At the top of any given module there will probably be imports and constants. Our
+preferred way of organizing them is as follows:
 
 ```
 # Built-in libraries:
@@ -67,8 +64,8 @@ Each of the sections should be sorted alphabetically.
 
 ## Write a TODO comment
 
-TODO comments should include the name of the person who wrote the TODO
-comment and a link to a GitHub issue describing the TODO in more depth.
+TODO comments should include the name of the person who wrote the TODO comment
+and a link to a GitHub issue describing the TODO in more depth.
 
 ## Write a commit message
 
@@ -97,4 +94,4 @@ A commit should almost always be linked to a GitHub issue.
 
 For:
 https://github.com/org/repo/issues/123
-```
+```

doc/tutorial.md

@@ -3,10 +3,11 @@
 ## Get started
 
 1. Install Python 3.12+.
-2. Install [Pipenv](https://pipenv.pypa.io/en/latest/index.html): `pip install --user pipenv`.
+2. Install [Pipenv](https://pipenv.pypa.io/en/latest/index.html):
+   `pip install --user pipenv`.
 3. Activate a virtual environment: `pipenv shell`.
 4. Install dependencies: `pipenv sync --dev`.
 5. Create a `.env` file based on `.env.template`.
 6. Seed the database: `inv dbseed`.
 7. Run the development server: `inv dev`.
-8. Install [yamlfmt](https://github.com/google/yamlfmt): `brew install yamlfmt`
+8. Install [yamlfmt](https://github.com/google/yamlfmt): `brew install yamlfmt`