refactor: enable linting of docs/custom_conf.py (#1330)

Revert previous edits to docs/conf.py, moving the changes to
docs/custom_conf.py, and enable linting for docs/custom_conf.py

The resulting linting errors have been resolved primarily via
`tool.ruff.lint.per-file-ignores`, with one inline noqa (`copyright`
variable shadows builtin), and the removal of a type annotation not in
scope (`Node`).

docs/conf.py

@@ -1,4 +1,3 @@
-# ruff: noqa
 import sys
 import os
 
@@ -99,6 +98,12 @@
 ]
 exclude_patterns.extend(custom_excludes)
 
+rst_epilog = '''
+.. include:: /reuse/links.txt
+'''
+if 'custom_rst_epilog' in locals():
+    rst_epilog = custom_rst_epilog
+
 source_suffix = {
     '.rst': 'restructuredtext',
     '.md': 'markdown',

docs/custom_conf.py

@@ -12,7 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# ruff: noqa
 import datetime
 import pathlib
 import sys
@@ -100,7 +99,7 @@ def _compute_navigation_tree(context):
 #   -H 'Accept: application/vnd.github.v3.raw' \
 #   https://api.github.com/repos/canonical/<REPO> | jq '.created_at'
 
-copyright = '%s, %s' % (datetime.date.today().year, author)
+copyright = '%s, %s' % (datetime.date.today().year, author)  # noqa: A001
 
 ## Open Graph configuration - defines what is displayed as a link preview
 ## when linking to the documentation from another website (see https://ogp.me/)
@@ -235,7 +234,7 @@ def _compute_navigation_tree(context):
 # Specify a reST string that is included at the end of each file.
 # If commented out, use the default (which pulls the reuse/links.txt
 # file into each reST file).
-# custom_rst_epilog = ''
+custom_rst_epilog = ''
 
 # By default, the documentation includes a feedback button at the top.
 # You can disable it by setting the following configuration to True.
@@ -409,7 +408,7 @@ def run(self):
         domain = self.env.get_domain('changeset')
         domain.note_changeset(node)
 
-        ret: list[Node] = [node]
+        ret = [node]
         ret += messages
         return ret
 

pyproject.toml

@@ -160,6 +160,7 @@ ignore = [
     # Unnecessary `tuple` call (rewrite as a literal)
     "C408",
 ]
+
 [tool.ruff.lint.per-file-ignores]
 "test/*" = [
     # All documentation linting.
@@ -181,6 +182,16 @@ ignore = [
     "S605",  # Starting a process with a shell: seems safe, but may be changed in the future; consider rewriting without `shell`
     "S607",  # Starting a process with a partial executable path
 ]
+"docs/custom_conf.py" = [
+    "D100",  # Missing docstring in public module
+    "D101",  # Missing docstring in public class
+    "D102",  # Missing docstring in public method
+    "D103",  # Missing docstring in public function
+    "E266",  # Too many leading `#` before block comment
+    "I001",  # Import block is un-sorted or un-formatted
+    "RUF003",  # Comment contains ambiguous unicode characters (EN DASH, RIGHT SINGLE QUOTATION MARK)
+    "UP031",  # Use format specifiers instead of percent format
+]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"