📝 Add documents for alternatives

sphinxcontrib-requirements-txt
sphinxcontrib-autofile

Author: Freed-Wu

.pre-commit-config.yaml

@@ -1,4 +1,3 @@
-#!/usr/bin/env -S pre-commit run -ac
 ---
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -23,11 +22,11 @@ repos:
       - id: check-toml
       - id: check-json
   - repo: https://github.com/Lucas-C/pre-commit-hooks
-    rev: v1.4.2
+    rev: v1.5.4
     hooks:
       - id: remove-crlf
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.2.4
+    rev: v2.2.5
     hooks:
       - id: codespell
         additional_dependencies:
@@ -39,24 +38,27 @@ repos:
         args:
           - --msg-filename
   - repo: https://github.com/editorconfig-checker/editorconfig-checker.python
-    rev: 2.7.1
+    rev: 2.7.2
     hooks:
       - id: editorconfig-checker
   - repo: https://github.com/jumanjihouse/pre-commit-hooks
     rev: 3.0.0
     hooks:
       - id: check-mailmap
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.6.25
+    hooks:
+      - id: actionlint
   - repo: https://github.com/adrienverge/yamllint
-    rev: v1.30.0
+    rev: v1.32.0
     hooks:
       - id: yamllint
   - repo: https://github.com/executablebooks/mdformat
     rev: 0.7.16
     hooks:
       - id: mdformat
-        args:
-          - --number
         additional_dependencies:
+          - mdformat-pyproject
           - mdformat-gfm
           - mdformat-myst
           - mdformat-toc
@@ -65,22 +67,22 @@ repos:
           - mdformat-black
           - mdformat-config
   - repo: https://github.com/DavidAnson/markdownlint-cli2
-    rev: v0.6.0
+    rev: v0.8.1
     hooks:
       - id: markdownlint-cli2
         additional_dependencies:
           - [email protected]
   - repo: https://github.com/Freed-Wu/pre-commit-hooks
-    rev: 0.0.10
+    rev: 0.0.11
     hooks:
       - id: update-CITATION.cff
       - id: update-pyproject.toml
   - repo: https://github.com/perltidy/perltidy
-    rev: "20230309.02"
+    rev: "20230701.02"
     hooks:
       - id: perltidy
   - repo: https://github.com/psf/black
-    rev: 23.1.0
+    rev: 23.7.0
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/isort
@@ -94,7 +96,7 @@ repos:
         additional_dependencies:
           - tomli
   - repo: https://github.com/kumaraditya303/mirrors-pyright
-    rev: v1.1.300
+    rev: v1.1.322
     hooks:
       - id: pyright
   - repo: https://github.com/PyCQA/bandit

README.md

@@ -114,6 +114,9 @@ examples.
 
 #### [Generate API Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/api/translate_shell.md)
 
+**Note**: A more "sphinx" solution is
+[sphinxcontrib-autofile](https://github.com/sphinx-contrib/autofile).
+
 Before:
 
 ````markdown
@@ -142,7 +145,7 @@ scripts/generate-api.md.pl src/*/*.py
 `````
 
 Where
-[`scripts/generate-api.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-api.md.pl)
+[`scripts/generate-api.md.pl`](https://github.com/sphinx-contrib/eval/blob/main/scripts/generate-api.md.pl)
 replaces all `src/translate_shell/XXX.py`s to
 
 ```rst
@@ -184,6 +187,9 @@ searches all `TODO`s in code then convert them to correct hyperlinks.
 
 #### [Generate Requirements Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/resources/requirements.md)
 
+**Note**: A more "sphinx" solution is
+[sphinxcontrib-requirements-txt](https://github.com/sphinx-contrib/requirements-txt).
+
 Before:
 
 ```markdown
@@ -210,7 +216,7 @@ generate-requirements.md.pl
 ````
 
 Where
-[`scripts/generate-requirements.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-requirements.md.pl)
+[`scripts/generate-requirements.md.pl`](https://github.com/sphinx-contrib/eval/blob/main/scripts/generate-requirements.md.pl)
 searches all `requirements/*.txt`s and `requirements/completion.txt` is:
 
 ```unixconfig

pyproject.toml

@@ -51,6 +51,9 @@ file = "requirements/dev.txt"
 file = "requirements/myst.txt"
 # end: scripts/update-pyproject.toml.pl
 
+[tool.mdformat]
+number = true
+
 [tool.black]
 line-length = 79
 

scripts/generate-requirements.md.pl

@@ -0,0 +1,10 @@
+#!/usr/bin/env -S perl -p
+$title = $ARGV;
+$title =~ s=.*?requirements/(.*?)\.txt=$1=;
+if (m(^[^#].*://)) {
+    s=(^.*://)(.*)=- [$1$2](https://$2)=;
+    next;
+}
+s`^([^#\n][^\s[>=<^!^]*)`- [$1](https://pypi.org/project/$1)`;
+s/^#\s*//;
+s/^!.*/## $title/;