Render documentation using Sphinx. (#1143)

.pydocstyle.ini

@@ -0,0 +1,2 @@
+[pydocstyle]
+ignore = D100, D101, D102, D103, D104, D105, D107, D200, D203, D212

.readthedocs.yaml

@@ -0,0 +1,11 @@
+version: 2
+build:
+  os: ubuntu-22.04
+  tools:
+    python: '3.12'
+sphinx:
+  configuration: documentation/conf.py
+python:
+  install:
+    - method: pip
+      path: .

betty/_resizeimage.py

@@ -1,5 +1,5 @@
 """
-This is a partial, simplified fork of the abandoned python-resize-image package.
+A partial, simplified fork of the abandoned python-resize-image package.
 
 This module exists purely because existing Betty code depended on an abandoned package, and that code has not been
 refactored yet.

betty/about.py

@@ -1,3 +1,5 @@
+"""Provide information about (this version of) Betty."""
+
 from __future__ import annotations
 
 import platform
@@ -40,6 +42,11 @@ def _indent_mapping_item(key: str, value: str, max_indentation: int) -> Iterator
 
 
 def report() -> str:
+    """
+    Produce a human-readable report about the current Betty installation.
+
+    :returns: A human-readable string in US English, using monospace indentation.
+    """
     return _indent_mapping({
         'Betty': version_label(),
         'Operating system': platform.platform(),

betty/app/__init__.py

@@ -417,7 +417,7 @@ def servers(self) -> Mapping[str, Server]:
                     if isinstance(extension, serve.ServerProvider)
                     for server in extension.servers
                 ),
-                serve.BuiltinServer(self),
+                serve.BuiltinAppServer(self),
                 DemoServer(),
             ]
         }

betty/app/extension/__init__.py

@@ -34,6 +34,7 @@ class ExtensionTypeImportError(ExtensionTypeError, ImportError):
     """
     Raised when an alleged extension type cannot be imported.
     """
+
     def __init__(self, extension_type_name: str):
         super().__init__(f'Cannot find and import an extension with name "{extension_type_name}".')
 
@@ -42,6 +43,7 @@ class ExtensionTypeInvalidError(ExtensionTypeError, ImportError):
     """
     Raised for types that are not valid extension types.
     """
+
     def __init__(self, extension_type: type):
         super().__init__(f'{extension_type.__module__}.{extension_type.__name__} is not an extension type class. Extension types must extend {Extension.__module__}.{Extension.__name__}.')
 

betty/app/extension/requirement.py

@@ -32,7 +32,8 @@ def localize(self, localizer: Localizer) -> str:
 
     def reduce(self) -> Requirement | None:
         """
-        Removes unnecessary components of this requirement.
+        Remove unnecessary components of this requirement.
+
         - Collections can flatten unnecessary hierarchies.
         - Empty decorators or collections can 'dissolve' themselves and return None.
 

betty/assets/betty.pot

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Betty VERSION\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2024-01-08 19:21+0000\n"
+"POT-Creation-Date: 2024-01-12 13:27+0000\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language-Team: LANGUAGE <LL@li.org>\n"
@@ -168,6 +168,9 @@ msgstr ""
 msgid "Beneficiary"
 msgstr ""
 
+msgid "Betty documentation"
+msgstr ""
+
 msgid "Betty helps you visualize and publish your family history by building interactive genealogy websites out of your <a href=\"{gramps_url}\">Gramps</a> and <a href=\"{gedcom_url}\">GEDCOM</a> family trees."
 msgstr ""
 
@@ -671,6 +674,9 @@ msgstr ""
 msgid "Serving the Betty demo..."
 msgstr ""
 
+msgid "Serving the Betty documentation..."
+msgstr ""
+
 msgid "Serving your site at {url}..."
 msgstr ""
 
@@ -833,6 +839,9 @@ msgstr ""
 msgid "View demo site..."
 msgstr ""
 
+msgid "View documentation"
+msgstr ""
+
 msgid "View site"
 msgstr ""
 
@@ -857,6 +866,9 @@ msgstr ""
 msgid "You can now view a Betty demonstration site at <a href=\"{url}\">{url}</a>."
 msgstr ""
 
+msgid "You can now view the documentation at <a href=\"{url}\">{url}</a>."
+msgstr ""
+
 msgid "You can now view your site at <a href=\"{url}\">{url}</a>."
 msgstr ""
 

betty/assets/locale/fr-FR/betty.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PROJECT VERSION\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2024-01-08 19:21+0000\n"
+"POT-Creation-Date: 2024-01-12 13:27+0000\n"
 "PO-Revision-Date: 2020-11-27 19:49+0100\n"
 "Last-Translator: \n"
 "Language: fr\n"
@@ -198,6 +198,9 @@ msgstr "Baptême"
 msgid "Beneficiary"
 msgstr "Bénéficiaire"
 
+msgid "Betty documentation"
+msgstr "Documentation de Betty"
+
 msgid ""
 "Betty helps you visualize and publish your family history by building "
 "interactive genealogy websites out of your <a "
@@ -759,6 +762,9 @@ msgstr ""
 msgid "Serving the Betty demo..."
 msgstr ""
 
+msgid "Serving the Betty documentation..."
+msgstr ""
+
 msgid "Serving your site at {url}..."
 msgstr ""
 
@@ -949,6 +955,9 @@ msgstr ""
 msgid "View demo site..."
 msgstr ""
 
+msgid "View documentation"
+msgstr ""
+
 msgid "View site"
 msgstr ""
 
@@ -975,6 +984,9 @@ msgid ""
 "href=\"{url}\">{url}</a>."
 msgstr ""
 
+msgid "You can now view the documentation at <a href=\"{url}\">{url}</a>."
+msgstr ""
+
 msgid "You can now view your site at <a href=\"{url}\">{url}</a>."
 msgstr ""
 

betty/assets/locale/nl-NL/betty.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: PROJECT VERSION\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2024-01-08 19:21+0000\n"
+"POT-Creation-Date: 2024-01-12 13:27+0000\n"
 "PO-Revision-Date: 2022-04-08 01:58+0100\n"
 "Last-Translator: \n"
 "Language: nl\n"
@@ -211,6 +211,9 @@ msgstr "Doping"
 msgid "Beneficiary"
 msgstr "Begunstigde"
 
+msgid "Betty documentation"
+msgstr "Betty-documentatie"
+
 msgid ""
 "Betty helps you visualize and publish your family history by building "
 "interactive genealogy websites out of your <a "
@@ -799,6 +802,9 @@ msgstr "Serveer site"
 msgid "Serving the Betty demo..."
 msgstr "De Betty-demo aan het serveren..."
 
+msgid "Serving the Betty documentation..."
+msgstr "De Betty-documentatie aan het serveren..."
+
 msgid "Serving your site at {url}..."
 msgstr "Je site op {url} aan het serveren..."
 
@@ -996,6 +1002,9 @@ msgstr "Bekijk een demonstratie van hoe een Betty-site eruit ziet"
 msgid "View demo site..."
 msgstr "Bekijk een demonstratiesite..."
 
+msgid "View documentation"
+msgstr "Bekijk documentatie"
+
 msgid "View site"
 msgstr "Bekijk site"
 
@@ -1022,6 +1031,9 @@ msgid ""
 "href=\"{url}\">{url}</a>."
 msgstr ""
 
+msgid "You can now view the documentation at <a href=\"{url}\">{url}</a>."
+msgstr "Je kan de documentatie nu bekijken op <a href=\"{url}\">{url}</a>."
+
 msgid "You can now view your site at <a href=\"{url}\">{url}</a>."
 msgstr "Je kan je site nu bekijken op <a href=\"{url}\">{url}</a>."
 

betty/assets/locale/uk/betty.po

@@ -7,7 +7,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Betty VERSION\n"
 "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n"
-"POT-Creation-Date: 2024-01-08 19:21+0000\n"
+"POT-Creation-Date: 2024-01-12 13:27+0000\n"
 "PO-Revision-Date: 2020-05-02 22:29+0100\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: uk\n"
@@ -198,6 +198,9 @@ msgstr "Хрещення"
 msgid "Beneficiary"
 msgstr "Бенефіціар"
 
+msgid "Betty documentation"
+msgstr ""
+
 msgid ""
 "Betty helps you visualize and publish your family history by building "
 "interactive genealogy websites out of your <a "
@@ -759,6 +762,9 @@ msgstr ""
 msgid "Serving the Betty demo..."
 msgstr ""
 
+msgid "Serving the Betty documentation..."
+msgstr ""
+
 msgid "Serving your site at {url}..."
 msgstr ""
 
@@ -948,6 +954,9 @@ msgstr ""
 msgid "View demo site..."
 msgstr ""
 
+msgid "View documentation"
+msgstr ""
+
 msgid "View site"
 msgstr ""
 
@@ -974,6 +983,9 @@ msgid ""
 "href=\"{url}\">{url}</a>."
 msgstr ""
 
+msgid "You can now view the documentation at <a href=\"{url}\">{url}</a>."
+msgstr ""
+
 msgid "You can now view your site at <a href=\"{url}\">{url}</a>."
 msgstr ""
 

betty/cli.py

@@ -12,7 +12,7 @@
 from PyQt6.QtWidgets import QMainWindow
 from click import get_current_context, Context, Option, Command, Parameter
 
-from betty import about, generate, load
+from betty import about, generate, load, documentation, fs
 from betty.app import App
 from betty.asyncio import sync, wait
 from betty.error import UserFacingError
@@ -98,6 +98,7 @@ async def _init_ctx_app(
 
     app = App()
     ctx.obj['commands'] = {
+        'docs': _docs,
         'clear-caches': _clear_caches,
         'demo': _demo,
         'gui': _gui,
@@ -270,6 +271,20 @@ async def _serve(app: App) -> None:
             await asyncio.sleep(999)
 
 
+@click.command(help='View the documentation.')
+@global_command
+async def _docs():
+    async with App() as app:
+        server = documentation.DocumentationServer(
+            fs.CACHE_DIRECTORY_PATH,
+            localizer=app.localizer,
+        )
+        async with server:
+            await server.show()
+            while True:
+                await asyncio.sleep(999)
+
+
 if about.is_development():
     @click.command(short_help='Initialize a new translation', help='Initialize a new translation.\n\nThis is available only when developing Betty.')
     @click.argument('locale')

betty/config.py

@@ -43,7 +43,6 @@ def load(
         """
         Load dumped configuration into a new configuration instance.
         """
-
         raise NotImplementedError(repr(cls))
 
     @classmethod

betty/documentation.py

@@ -0,0 +1,72 @@
+import asyncio
+import logging
+import os
+import shutil
+from contextlib import suppress, AsyncExitStack
+from pathlib import Path
+from subprocess import CalledProcessError
+from tempfile import TemporaryDirectory
+
+from betty import subprocess, serve
+from betty.locale import Str, Localizer
+from betty.serve import Server, NoPublicUrlBecauseServerNotStartedError
+
+
+async def _build_cache(cache_directory_path: Path) -> Path:
+    cache_directory_path /= 'docs'
+    if not cache_directory_path.exists():
+        await _build(cache_directory_path)
+    return cache_directory_path
+
+
+async def _build(output_directory_path: Path) -> None:
+    with suppress(FileExistsError):
+        await asyncio.to_thread(os.makedirs, output_directory_path)
+    with TemporaryDirectory() as working_directory_path:
+        source_directory_path = Path(working_directory_path) / 'source'
+        await asyncio.to_thread(shutil.copytree, Path(__file__).parent.parent / 'documentation', source_directory_path)
+        await asyncio.to_thread(shutil.copy2, Path(__file__).parent.parent / 'betty' / 'assets' / 'public' / 'static' / 'betty-32x32.png', source_directory_path / 'betty-logo.png')
+        try:
+            await subprocess.run_exec(['sphinx-apidoc', '--force', '--separate', '-d', '999', '-o', str(source_directory_path), 'betty', 'betty/tests'])
+            await subprocess.run_exec(['sphinx-build', str(source_directory_path), str(output_directory_path)])
+        except CalledProcessError as e:
+            if e.stderr is not None:
+                logging.getLogger().error(e.stderr)
+            raise
+
+
+class DocumentationServer(Server):
+    def __init__(
+        self,
+        cache_directory_path: Path,
+        *,
+        localizer: Localizer,
+    ):
+        super().__init__(localizer)
+        self._cache_directory_path = cache_directory_path
+        self._server: Server | None = None
+        self._exit_stack = AsyncExitStack()
+
+    @classmethod
+    def label(cls) -> Str:
+        return Str._('Betty documentation')
+
+    @property
+    def public_url(self) -> str:
+        if self._server is not None:
+            return self._server.public_url
+        raise NoPublicUrlBecauseServerNotStartedError()
+
+    async def start(self) -> None:
+        await super().start()
+        try:
+            www_directory_path = await _build_cache(self._cache_directory_path)
+            self._server = serve.BuiltinServer(www_directory_path, localizer=self._localizer)
+            await self._exit_stack.enter_async_context(self._server)
+        except BaseException:
+            await self.stop()
+            raise
+
+    async def stop(self) -> None:
+        await self._exit_stack.aclose()
+        await super().stop()

betty/error.py

@@ -28,6 +28,7 @@ class UserFacingError(Exception, Localizable):
     This type of error is fatal, but fixing it does not require knowledge of Betty's internals or the stack trace
     leading to the error. It must therefore have an end-user-friendly message, and its stack trace must not be shown.
     """
+
     def __init__(self, message: Localizable):
         super().__init__(
             # Provide a default localization so this exception can be displayed like any other.