doc: add automatic screenshots in the documentation

yaal-coop · Jan 13, 2025 · 80ee6fb · 80ee6fb
1 parent 68fc2f2
commit 80ee6fb
Show file tree

Hide file tree

Showing 39 changed files with 412 additions and 46 deletions.
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -108,4 +108,5 @@ jobs:
       - run: |
           export TZ=UTC
           uv sync --group doc --all-extras
+          uv run playwright install firefox
           uv run sphinx-build doc build/sphinx/html --fail-on-warning
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -75,5 +75,6 @@ doc:
   stage: test
   script:
     - uv sync --group doc --all-extras
+    - uv run playwright install firefox
     - uv run sphinx-build doc build/sphinx/html --fail-on-warning
     - uv cache prune --ci
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -17,3 +17,4 @@ build:
     post_install:
       - pip install .
       - pip install --requirement requirements.txt
+      - playwright install firefox
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,10 @@
 [0.0.59] - 2025-01-10
 ---------------------
 
+Added
+^^^^^
+- Add screenshots in the documentation. :issue:`210`
+
 Fixed
 ^^^^^
 - Fix password fields auto-refilling when input is reset. :issue:`218` :pr:`215`

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -212,6 +212,18 @@ You can also run sphinx by hand, that should be faster since it avoids the tox e
 
 The generated documentation is located at ``build/sphinx/html/en``.
 
+.. note::
+
+   The documentation generates dynamic screenshots of Canaille using `sphinxcontrib-screenshot`_, that internally uses `Playwright`_.
+   Playwright needs to be initialized with the following command:
+
+   .. code-block:: bash
+
+      uv run playwright install firefox
+
+.. _sphinxcontrib-screenshot: https://sphinxcontrib-screenshot.readthedocs.io
+.. _Playwright: https://playwright.dev/python
+
 Code translation
 ----------------
 

diff --git a/README.md b/README.md
@@ -13,14 +13,6 @@ It aims to be very light, simple to install and simple to maintain. Its main fea
 - Customizable, themable;
 - The code is easy to read and easy to edit!
 
-# Screenshots
-
-<div align="center">
-    <img src="doc/_static/login.webp" width="225" alt="Canaille login page" />
-    <img src="doc/_static/profile.webp" width="225" alt="Canaille profile page" />
-    <img src="doc/_static/consent.webp" width="225" alt="Canaille consent page" />
-</div>
-
 # Try it!
 
 ## Locally

diff --git a/canaille/templates/core/about.html b/canaille/templates/core/about.html
@@ -1,9 +1,18 @@
 {#
+.. screenshot:: |canaille|/about
+   :align: right
+   :context: user
+   :width: 275px
+
+   The 'About' page.
+
 The 'About' page.
+
 This is an informational page, displaying the project links.
 
 :param version: The current Canaille version.
 :type version: :class:`str`
+
 #}
 
 {% extends theme('base.html') %}

diff --git a/canaille/templates/core/firstlogin.html b/canaille/templates/core/firstlogin.html
@@ -1,4 +1,12 @@
-{# The first login page.
+{#
+.. screenshot:: |canaille|/firstlogin/james
+   :context: james
+   :align: right
+   :width: 275px
+
+   The first login page.
+
+The first login page.
 
 This page is displayed to users who do not have set a password yet.
 #}

diff --git a/canaille/templates/core/forgotten-password.html b/canaille/templates/core/forgotten-password.html
@@ -1,6 +1,14 @@
-{# Password forgotten page.
+{#
+.. screenshot:: |canaille|/reset
+   :align: right
+   :width: 275px
+
+   The password reinitialization page.
+
+Password forgotten page.
 
 This page displays a form asking for the email address of users who cannot remember their password.
+
 #}
 {% extends theme('base.html') %}
 {% import 'macro/form.html' as fui %}

diff --git a/canaille/templates/core/group.html b/canaille/templates/core/group.html
@@ -1,4 +1,12 @@
-{# Group edition page.
+{#
+.. screenshot:: |canaille|/groups/admins
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The group edition page.
+
+Group edition page.
 
 Displays the group edition or creation form.
 

diff --git a/canaille/templates/core/groups.html b/canaille/templates/core/groups.html
@@ -1,4 +1,12 @@
-{# The group list page.
+{#
+.. screenshot:: |canaille|/groups
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The group list page.
+
+The group list page.
 
 :param table: A :class:`~canaille.core.models.Group` pagination form.
 :type table: :class:`~canaille.app.forms.TableForm`

diff --git a/canaille/templates/core/invite.html b/canaille/templates/core/invite.html
@@ -1,4 +1,12 @@
-{# The invitation form page.
+{#
+.. screenshot:: |canaille|/invite
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The invitation form page.
+
+The invitation form page.
 
 Displays the invitation form to users with the invitation permission.
 

diff --git a/canaille/templates/core/login.html b/canaille/templates/core/login.html
@@ -1,4 +1,11 @@
-{# The login page.
+{#
+.. screenshot:: |canaille|/login
+   :align: right
+   :width: 275px
+
+   The login page.
+
+The login page.
 
 This page displays a form to get the user identifier.
 

diff --git a/canaille/templates/core/profile_add.html b/canaille/templates/core/profile_add.html
@@ -1,4 +1,10 @@
-{# User account creation page.
+{#
+.. screenshot:: |canaille|/profile
+   :context: admin
+   :align: right
+   :width: 275px
+
+User account creation page.
 
 This template displays an account creation form.
 It is used in the registration page, and in the manual account creation page available for users with *user management* permission.

diff --git a/canaille/templates/core/profile_edit.html b/canaille/templates/core/profile_edit.html
@@ -1,4 +1,12 @@
-{# The profile edition template.
+{#
+.. screenshot:: |canaille|/profile/user
+   :context: user
+   :align: right
+   :width: 275px
+
+   The user profile edition page.
+
+The profile edition template.
 
 Displays a user profile edition form.
 

diff --git a/canaille/templates/core/profile_settings.html b/canaille/templates/core/profile_settings.html
@@ -1,4 +1,12 @@
-{# The profile settings template.
+{#
+.. screenshot:: |canaille|/profile/user/settings
+   :context: user
+   :align: right
+   :width: 275px
+
+   The user profile settings edition page.
+
+The profile settings template.
 
 Displays the user settings edition form.
 

diff --git a/canaille/templates/core/reset-password.html b/canaille/templates/core/reset-password.html
@@ -1,4 +1,11 @@
-{# The password reset template.
+{#
+.. screenshot:: |canaille|/reset
+   :align: right
+   :width: 275px
+
+   The password reset page.
+
+The password reset template.
 
 Displays a password reset form.
 

diff --git a/canaille/templates/core/users.html b/canaille/templates/core/users.html
@@ -1,4 +1,10 @@
-{# The users list.
+{#
+.. screenshot:: |canaille|/users
+   :context: admin
+   :align: right
+   :width: 275px
+
+The users list.
 
 Displays a paginated list of :class:`~canaille.core.models.User`.
 

diff --git a/canaille/templates/oidc/authorization_list.html b/canaille/templates/oidc/authorization_list.html
@@ -1,4 +1,12 @@
-{# The list of authorizations.
+{#
+.. screenshot:: |canaille|/admin/authorization
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The list of authorizations.
+
+The list of authorizations.
 
 Displays a paginated list of :class:`~canaille.oidc.basemodels.AuthorizationCode`.
 

diff --git a/canaille/templates/oidc/authorize.html b/canaille/templates/oidc/authorize.html
@@ -1,4 +1,12 @@
-{# Consent request template.
+{#
+.. screenshot:: |canaille|/oauth/authorize?response_type=code&client_id=client1&redirect_uri=http%3A%2F%2Flocalhost%3A5001%2Flogin_callback&scope=openid+profile+email+phone+address+groups&state=state&nonce=nonce
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The consent request dialog.
+
+Consent request template.
 
 This templates is displayed to users accessing a new application that requests to access to personal information.
 It lists the personal information requested by the application, and offers the user to accept or decline.

diff --git a/canaille/templates/oidc/client_add.html b/canaille/templates/oidc/client_add.html
@@ -1,4 +1,12 @@
-{# The client addition template.
+{#
+.. screenshot:: |canaille|/admin/client/add
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The client addition page.
+
+The client addition template.
 
 Displays a form to create a new :class:`~canaille.oidc.basemodels.Client`.
 

diff --git a/canaille/templates/oidc/client_edit.html b/canaille/templates/oidc/client_edit.html
@@ -1,4 +1,12 @@
-{# The client edition template.
+{#
+.. screenshot:: |canaille|/admin/client/edit/client1
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The client addition page.
+
+The client edition template.
 
 Displays a form to edit a :class:`~canaille.oidc.basemodels.Client`.
 

diff --git a/canaille/templates/oidc/client_list.html b/canaille/templates/oidc/client_list.html
@@ -1,4 +1,10 @@
-{# The list of OIDC clients.
+{#
+.. screenshot:: |canaille|/admin/client
+   :context: admin
+   :align: right
+   :width: 275px
+
+The list of OIDC clients.
 
 Displays a paginated list of :class:`~canaille.oidc.basemodels.Client`.
 

diff --git a/canaille/templates/oidc/consent_list.html b/canaille/templates/oidc/consent_list.html
@@ -1,3 +1,24 @@
+{#
+.. screenshot:: |canaille|/consent
+   :context: user
+   :align: right
+   :width: 275px
+
+   The consented applications list.
+
+The consented applications list.
+
+Display a list of clients for which users have given or revoked their consent.
+
+:param scope_details: Description of the OIDC scopes.
+:type scope_details: :class:`dict`
+:param ignored_scopes: The scopes to hide.
+:type ignored_scopes: :class:`list`
+:param nb_consents: The number of consents.
+:type nb_consents: :class:`int`
+:param nb_preconsents: The number of preconsented clients.
+:type nb_preconsents: :class:`int`
+#}
 {% extends theme('base.html') %}
 
 {%- block title -%}

diff --git a/canaille/templates/oidc/preconsent_list.html b/canaille/templates/oidc/preconsent_list.html
@@ -1,4 +1,12 @@
-{# The preconsented applications list.
+{#
+.. screenshot:: |canaille|/consent/pre-consents
+   :context: user
+   :align: right
+   :width: 275px
+
+   The preconsented applications list.
+
+The preconsented applications list.
 
 Display a list of trusted clients for which it is implied that users don't need to explicitly give their consent.
 

diff --git a/canaille/templates/oidc/token_list.html b/canaille/templates/oidc/token_list.html
@@ -1,4 +1,12 @@
-{# The list of tokens.
+{#
+.. screenshot:: |canaille|/admin/token
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The list of tokens.
+
+The list of tokens.
 
 Displays a paginated list of :class:`~canaille.oidc.basemodels.Token`.
 

diff --git a/canaille/templates/oidc/token_view.html b/canaille/templates/oidc/token_view.html
@@ -1,4 +1,12 @@
-{# The token edition template.
+{#
+.. screenshot:: |canaille|/admin/token/EZWsi6omQRbJjWeq7rk8vcBVYz4PNbBXov97Z1D4mqxZgyQv
+   :context: admin
+   :align: right
+   :width: 275px
+
+   The token view page.
+
+The token view template.
 
 Displays the details of a token :class:`~canaille.oidc.basemodels.Token`.