Lint Markdown files

.markdownlint.jsonc

@@ -0,0 +1,10 @@
+{
+  "default": true,
+  "MD010": {
+    "code_blocks": false
+  },
+  "MD013": {
+    "code_blocks": false,
+    "tables": false
+  }
+}

.pre-commit-config.yaml

@@ -21,3 +21,15 @@ repos:
     additional_dependencies:
     - flake8-bugbear==23.9.16
     - flake8-comprehensions==3.14.0
+- repo: https://github.com/igorshubovych/markdownlint-cli
+  rev: v0.37.0
+  hooks:
+  - id: markdownlint
+- repo: https://github.com/thlorenz/doctoc
+  rev: v2.2.0
+  hooks:
+  - id: doctoc
+    files: |
+      (?x)^(
+        CONTRIBUTING\.md
+      )

CONTRIBUTING.md

@@ -10,12 +10,13 @@ submission!
 
 There are many ways to contribute:
 
-* submitting bug reports,
-* or writing code which can be incorporated into AMClient itself.
+- submitting bug reports,
+- or writing code which can be incorporated into AMClient itself.
+
+## Table of contents
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**
 
 - [Submitting bugs](#submitting-bugs)
 - [Contribution standards](#contribution-standards)
@@ -28,7 +29,7 @@ There are many ways to contribute:
 ## Submitting bugs
 
 If you find a security vulnerability, do NOT open an issue. Email
-[email protected] instead.
+<[email protected]> instead.
 
 Issues should be filed in our collective
 [Archivematica related issues repository][am-issues]
@@ -39,12 +40,12 @@ mailing list is always welcome!
 
 Useful questions to answer if you're having problems include:
 
-* What version of AMClient are you using?
-* How was it installed?
-* How was AMClient being used when this issue occurred?
-* What was the expected outcome?
-* What was the actual outcome?
-* Can we reproduce this reliably?
+- What version of AMClient are you using?
+- How was it installed?
+- How was AMClient being used when this issue occurred?
+- What was the expected outcome?
+- What was the actual outcome?
+- Can we reproduce this reliably?
 
 ## Contribution standards
 
@@ -62,7 +63,7 @@ The Archivematica contributor's agreement is based almost verbatim on the
 [contributor license][contributor-license].
 
 If you have any questions or concerns about the Contributor's Agreement, please
-email us at [email protected] to discuss them.
+email us at <[email protected]> to discuss them.
 
 ### Why do I have to sign a Contributor's Agreement?
 
@@ -89,13 +90,15 @@ than fighting legal battles over contributions.
 
 Please print out, read, sign, and scan the
 [contributor agreement][contributors-agreement] and email it to
-[email protected]. Alternatively, you may send an original signed
+<[email protected]>. Alternatively, you may send an original signed
 agreement to:
 
-    Artefactual Systems Inc.
-    201 - 301 Sixth Street
-    New Westminster BC  V3L 3A7
-    Canada
+```text
+Artefactual Systems Inc.
+201 - 301 Sixth Street
+New Westminster BC  V3L 3A7
+Canada
+```
 
 [am-issues]: https://github.com/archivematica/issues
 [am-forum]: https://groups.google.com/forum/#!forum/archivematica

README.md

@@ -1,8 +1,8 @@
+# amclient
+
 [![GitHub CI](https://github.com/artefactual-labs/amclient/actions/workflows/test.yml/badge.svg)](https://github.com/artefactual-labs/amclient/actions/workflows/test.yml)
 [![codecov](https://codecov.io/gh/artefactual-labs/amclient/branch/master/graph/badge.svg?token=hJLGYzoJUo)](https://codecov.io/gh/artefactual-labs/amclient)
 
-# amclient
-
 AMClient is an Archivematica API client library and Python package for making
 it easier to talk to Archivematica from your Python scripts. AMClient also acts
 as a command line application which can easily be combined with shell-scripts
@@ -15,13 +15,17 @@ Archivematica components:
 * [Storage Service API][storage-service-api]
 
 Basic usage:
-    `amclient.py <subcommand> [optional arguments] <positional argument(s)>`
 
-  E.g.:
-  ```bash
-    amclient.py close-completed-transfers \
-        --am-user-name test 234deffdf89d887a7023546e6bc0031167cedf6
-  ```
+```shell
+amclient.py <subcommand> [optional arguments] <positional argument(s)>
+```
+
+E.g.:
+
+```shell
+amclient.py close-completed-transfers \
+    --am-user-name test 234deffdf89d887a7023546e6bc0031167cedf6
+```
 
 To see a list of all commands and how they are used, then run `amclient.py`
 without any arguments.
@@ -30,28 +34,30 @@ To understand how to use an individual subcommand, simply run:
 `amclient.py <subcommand>`, the output will describe the input parameters for
 that command:
 
-  E.g.:
-  ```bash
-    usage: amclient extract-file [-h] [--ss-user-name USERNAME] [--ss-url URL]
-                                 [--directory DIR]
-                                 [--saveas-filename SAVEASFILENAME]
-                                 ss_api_key package_uuid relative_path
-  ```
+E.g.:
+
+```shell
+usage: amclient extract-file [-h] [--ss-user-name USERNAME] [--ss-url URL]
+                              [--directory DIR]
+                              [--saveas-filename SAVEASFILENAME]
+                              ss_api_key package_uuid relative_path
+```
 
 Calling the module from Python:
 
-  E.g.:
+E.g.:
+
 ```python
-    Python 3.6.7 (default, Oct 22 2018, 11:32:17)
-    [GCC 8.2.0] on linux
-    Type "help", "copyright", "credits" or "license" for more information.
-    >>> from amclient import AMClient
-    >>> am = AMClient()
-    >>> am.ss_url = "http://127.0.0.1:62081"
-    >>> am.ss_user_name = "test"
-    >>> am.ss_api_key = "test"
-    >>> am.list_storage_locations()
-    ...json is output here...
+  Python 3.9.18 (main, Nov 14 2023, 15:21:53)
+  [GCC 11.4.0] on linux
+  Type "help", "copyright", "credits" or "license" for more information.
+  >>> from amclient import AMClient
+  >>> am = AMClient()
+  >>> am.ss_url = "http://127.0.0.1:62081"
+  >>> am.ss_user_name = "test"
+  >>> am.ss_api_key = "test"
+  >>> am.list_storage_locations()
+  ...json is output here...
 ```
 
 ## CONTRIBUTING