🎨 Format pyproject.toml

Update docs about AUR
Add py.typed
Add FUNDING.yml
Add doq template and regenerate all docstrings
Fix bug that scripts/ is not in $PATH

Author: Freed-Wu

.github/FUNDING.yml

@@ -0,0 +1,5 @@
+---
+custom:
+  - "https://user-images.githubusercontent.com/32936898/199681341-1c5cfa61-4411-4b67-b268-7cd87c5867bb.png"
+  - "https://user-images.githubusercontent.com/32936898/199681363-1094a0be-85ca-49cf-a410-19b3d7965120.png"
+  - "https://user-images.githubusercontent.com/32936898/199681368-c34c2be7-e0d8-43ea-8c2c-d3e865da6aeb.png"

.readthedocs.yaml

@@ -9,11 +9,7 @@ build:
   tools:
     python: "3"
 
-sphinx:
-  configuration: docs/conf.py
-
-formats:
-  - pdf
+formats: all
 
 python:
   install:

README.md

@@ -65,15 +65,15 @@ For myst:
 
 ````markdown
 ```{eval-sh}
-echo My OS is $OSTYPE
+echo My OS is $OSTYPE.
 ```
 ````
 
 For rst:
 
 ```rst
 .. eval-sh::
-    echo My OS is $OSTYPE
+    echo My OS is $OSTYPE.
 
 ```
 
@@ -86,12 +86,13 @@ sphinx-build docs docs/_build/html
 Result:
 
 ```text
-My OS is linux-gnu
+My OS is linux-gnu.
 ```
 
 ### Advanced Usages
 
-All the following code is myst. The corresponding rst is similar.
+All of the following examples are myst. The corresponding examples of rst are
+similar. Remember to add `scripts` to your `$PATH` in `docs/conf.py`.
 Click the hyperlink of title to see the actual example.
 
 #### [Generate API Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/api/translate_shell.md)
@@ -117,23 +118,24 @@ Now
 
 ````{eval-rst}
 ```{eval-sh}
-scripts/generate-api.md.sh '' -maxdepth 1
+generate-api.md.sh '' -maxdepth 1
 ```
 ````
 `````
 
 Where `scripts/generate-api.md.sh` is a script which search all python file and
-replace them from `src/translate_shell/X/Y/Z.py` to
+replace them from `src/translate_shell/XXX.py` to
 
 ```rst
-.. automodule:: translate_shell.X.Y.Z`
+.. automodule:: translate_shell.XXX
     :members:
 ```
 
 ```bash
 #!/usr/bin/env bash
 # shellcheck disable=SC2086
-find src/sphinxcontrib/eval/$1 $2 $3 -name '*.py' |
+cd "$(dirname "$(dirname "$0")")" || exit 1
+find src/translate_shell/$1 $2 $3 -name '*.py' |
 perl -pe's=src/=.. automodule:: =g;
 s=\.py$=\n    :members:=g;s=/__init__==g;s=/=.=g'
 ```
@@ -142,38 +144,40 @@ s=\.py$=\n    :members:=g;s=/__init__==g;s=/=.=g'
 
 Before:
 
-<!-- markdownlint-disable MD013-->
-
 ```markdown
 # TODO
 
-- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L4> more stardicts.
-- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L5> Create different subclasses for different dict to get phonetic, explains
-- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/ui/repl.py#L33> make the last line gray like ptpython
-  ...
+- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L4>
+  more stardicts.
+- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L5>
+  Create different subclasses for different dict to get phonetic, explains
+- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/ui/repl.py#L33>
+  make the last line gray like ptpython
+- ...
 ```
 
-<!-- markdownlint-enable MD013-->
-
 Now:
 
 ````markdown
 # TODO
 
 ```{eval-sh}
-scripts/generate-todo.md.sh
+generate-todo.md.sh
 ```
 ````
 
-Where the script searches all `TODO`s in code then convert them to correct hyperlinks.
+Where `scripts/generate-todo.md.sh` searches all `TODO`s in code then convert
+them to correct hyperlinks.
 
 ```sh
-grep -RIn TODO: src | perl -pe's/:/#L/;s/:\s*#?\s*TODO:\s*/ /;
+#!/usr/bin/env bash
+cd "$(dirname "$(dirname "$0")")" || exit 1
+grep -RIn TODO: src | perl -pe's/:/#L/;s/:\s*#?\s*TODO:\s*/  /;
 s=^=- https://github.com/Freed-Wu/tranlate-shell/tree/main/=g;
-s=(https://\S+)=<\1>=g'
+s=(https://\S+)=<\1>=g;s=^(- \S+)=\1\n=g'
 ```
 
-#### [Generate Requirement Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/resources/requirements.md)
+#### [Generate Requirements Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/resources/requirements.md)
 
 Before:
 
@@ -195,22 +199,23 @@ Now
 # Requirements
 
 ```{eval-sh}
-scripts/generate-requirements.md.sh
+generate-requirements.md.sh
 ```
 ````
 
-Where
+Where `scripts/generate-requirements.md.sh` searches all `requirements/*.txt`s:
 
 ```bash
 #!/usr/bin/env bash
-for file in requirements.txt requirements/*.txt ; do
+cd "$(dirname "$(dirname "$0")")" || exit 1
+for file in requirements/*.txt ; do
     filename="${file##*/}"
     perl -pe's=^([^#\n]\S*)=- [\1](https://pypi.org/project/\1)=g;
     s/^#\s*//g;s/^!.*/## '"${filename%%.txt}"'/g' < "$file"
 done
 ```
 
-And `requirements/completion.txt`:
+And `requirements/completion.txt` is:
 
 ```unixconfig
 #!/usr/bin/env -S pip install -r

docs/api/eval.md

@@ -2,6 +2,6 @@
 
 ````{eval-rst}
 ```{eval-sh}
-scripts/generate-api.md.sh
+generate-api.md.sh
 ```
 ````

docs/conf.py

@@ -12,6 +12,9 @@
 except ImportError:
     import tomli as tomllib
 
+scriptdir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "scripts")
+os.environ["PATH"] = scriptdir + os.path.pathsep + os.getenv("PATH", "")
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,

docs/resources/install.md

@@ -10,6 +10,12 @@ pip install sphinxcontrib-eval
 pip uninstall sphinxcontrib-eval
 ```
 
-## AUR
+## [AUR](https://aur.archlinux.org/packages/python-sphinxcontrib-eval)
 
-Not yet.
+```sh
+yay -S python-sphinxcontrib-eval
+```
+
+```sh
+sudo pacman -R python-sphinxcontrib-eval
+```

docs/resources/requirements.md

@@ -1,5 +1,5 @@
 # Requirements
 
 ```{eval-sh}
-scripts/generate-requirements.md.sh
+generate-requirements.md.sh
 ```

pyproject.toml

@@ -37,6 +37,9 @@ Source = "https://github.com/Freed-Wu/sphinxcontrib-eval"
 [tool.setuptools_scm]
 write_to = "src/sphinxcontrib/eval/_version.py"
 
+[tool.setuptools.package-data]
+"sphinxcontrib.eval" = ["py.typed"]
+
 [tool.setuptools.dynamic]
 dependencies = { file = "requirements.txt" }
 
@@ -55,19 +58,14 @@ profile = "black"
 [tool.pydocstyle]
 add_ignore = "D205, D400"
 
+[tool.doq]
+template_path = "templates"
+
 [tool.bandit]
-skips = [
-    "B404",
-]
+skips = ["B404"]
 
 [tool.bandit.assert_used]
-skips = [
-    "tests/*.py",
-    "*_test.py",
-    "test_*.py",
-]
+skips = ["tests/*.py", "*_test.py", "test_*.py"]
 
 [tool.coverage.report]
-exclude_lines = [
-  "if TYPE_CHECKING:"
-]
+exclude_lines = ["if TYPE_CHECKING:", "if __name__ == .__main__.:"]

scripts/generate-api.md.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 # shellcheck disable=SC2086
+cd "$(dirname "$(dirname "$0")")" || exit 1
 find src/sphinxcontrib/eval/$1 $2 $3 -name '*.py' |
 	perl -pe's=src/=.. automodule:: =g;
   s=\.py$=\n    :members:=g;s=/__init__==g;s=/=.=g'

scripts/generate-requirements.md.sh

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+cd "$(dirname "$(dirname "$0")")" || exit 1
 for file in requirements.txt requirements/*.txt; do
 	filename="${file##*/}"
 	perl -pe's=^([^#\n]\S*)=- [\1](https://pypi.org/project/\1)=g;