chore: updated documentation and dependencies

adrienbrignon · Mar 24, 2024 · 053dffe · 053dffe
1 parent 868722a
commit 053dffe
Show file tree

Hide file tree

Showing 14 changed files with 356 additions and 241 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -21,7 +21,7 @@ RUN apt-get update \
 
 FROM base as builder
 
-ENV POETRY_VERSION=1.7.1 \
+ENV POETRY_VERSION=1.8.2 \
     PIP_NO_CACHE_DIR=1 \
     PIP_DEFAULT_TIMEOUT=100 \
     PIP_DISABLE_PIP_VERSION_CHECK=1
@@ -42,6 +42,6 @@ RUN . .venv/bin/activate \
  && make build
 
 
-FROM docker.io/nginx:1.25.3
+FROM docker.io/nginx:1.25.4
 
 COPY --from=builder /usr/src/app/dist /usr/share/nginx/html
diff --git a/docs/.pages b/docs/.pages
@@ -1,4 +1,5 @@
 nav:
   - getting-started.md
   - setup
+  - reference
   - samples
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -38,4 +38,4 @@ plugins:
   - exporter
 ```
 
-Check out the [setup guides](../setup/setting-up-documents) for more details about how to use and configure the plugin.
+Check out the [setup guides](setup/setting-up-documents.md) for more details about how to use and configure the plugin.
diff --git a/docs/reference/configuration/base.md b/docs/reference/configuration/base.md
@@ -0,0 +1,13 @@
+# Base
+
+The configuration of the `exporter` plugin.
+
+## Schemas
+
+You can find the source code of the following schemas [here](https://github.com/adrienbrignon/mkdocs-exporter/blob/master/mkdocs_exporter/config.py).
+
+### `Configuration`
+
+| Name                 | Type                   | Default  | Description                                                  |
+|----------------------|------------------------|----------|--------------------------------------------------------------|
+| `theme`              | `str`                  |          | Overrides the theme used by your MkDocs instance.            |
diff --git a/docs/reference/configuration/extras.md b/docs/reference/configuration/extras.md
@@ -0,0 +1,37 @@
+# Extras
+
+The configuration of the `exporter-extras` plugin.
+
+## Schemas
+
+You can find the source code of the following schemas [here](https://github.com/adrienbrignon/mkdocs-exporter/blob/master/mkdocs_exporter/plugins/extras/config.py).
+
+### `Configuration`
+
+| Name                 | Type                                 | Default  | Description                                                  |
+|----------------------|--------------------------------------|----------|--------------------------------------------------------------|
+| `enabled`            | `bool`                               | `true`   | Should the plugin be enabled?                                |
+| `buttons`            | <code>list[[Button](#button)]</code> |          | The custom buttons to define.                                |
+
+### `Button`
+
+| Name                 | Type                                 | Default  | Description                                                  |
+|----------------------|--------------------------------------|----------|--------------------------------------------------------------|
+| `enabled`            | `bool | Callable`                    | `true`   | Is this button enabled (visible)?                            |
+| `title`              | `str | Callable`                     |          | The button's title.                                          |
+| `icon`               | `str | Callable`                     |          | The button's icon.                                           |
+| `attributes`         | `dict | Callable`                    |          | Custom HTML attributes to apply to the button.               |
+
+## Example
+
+```yaml
+plugins:
+  - exporter-extras:
+      buttons:
+        - title: Download as PDF
+          icon: material-file-download-outline
+          enabled: !!python/name:mkdocs_exporter.plugins.pdf.button.enabled
+          attributes:
+            href: !!python/name:mkdocs_exporter.plugins.pdf.button.href
+            download: !!python/name:mkdocs_exporter.plugins.pdf.button.download
+```
diff --git a/docs/reference/configuration/pdf.md b/docs/reference/configuration/pdf.md
@@ -0,0 +1,52 @@
+# PDF
+
+The configuration of the `exporter-pdf` plugin.
+
+## Schemas
+
+You can find the source code of the following schemas [here](https://github.com/adrienbrignon/mkdocs-exporter/blob/master/mkdocs_exporter/plugins/pdf/config.py).
+
+### `Configuration`
+
+| Name                 | Type                                 | Default  | Description                                                          |
+|----------------------|--------------------------------------|----------|----------------------------------------------------------------------|
+| `enabled`            | `bool`                               | `true`   | Should the plugin be enabled?                                        |
+| `explicit`           | `bool`                               | `false`  | Should pages specify explicitly that they should be rendered as PDF? |
+| `concurrency`        | `int`                                | `4`      | The maximum number of concurrent PDF generation tasks.               |
+| `stylesheets`        | `list[str]`                          |          | A list of custom stylesheets to apply before rendering documents.    |
+| `scripts`            | `list[str]`                          |          | A list of custom scripts to inject before rendering documents.       |
+| `covers`             | <code>[Covers](#covers)</code>       |          | The document's cover pages.                                          |
+| `browser`            | <code>[Browser](#browser)</code>     |          | The browser's configuration.                                         |
+| `url`                | `str`                                |          | The base URL that'll be prefixed to links with a relative path.      |
+
+### `Covers`
+
+| Name                 | Type                                 | Default  | Description                                                       |
+|----------------------|--------------------------------------|----------|-------------------------------------------------------------------|
+| `front`              | `str`                                |          | The front cover template location.                                |
+| `back`               | `str`                                |          | The back cover template location.                                 |
+
+### `Browser`
+
+| Name                 | Type                                 | Default  | Description                                                       |
+|----------------------|--------------------------------------|----------|-------------------------------------------------------------------|
+| `debug`              | `bool`                               | `false`  | Should console messages sent to the browser be logged?            |
+| `headless`           | `bool`                               | `true`   | Should the browser start in headless mode?                        |
+| `timeout`            | `int`                                | `60000`  | The timeout (in milliseconds) when waiting for the PDF to render. |
+
+## Example
+
+```yaml
+plugins:
+  - exporter-pdf:
+      concurrency: 8
+      enabled: !ENV [MKDOCS_EXPORTER_PDF, true]
+      stylesheets:
+        - resources/stylesheets/pdf.scss
+      covers:
+        front: resources/templates/covers/front.html.j2
+        back: resources/templates/covers/back.html.j2
+      browser:
+        debug: false
+        headless: true
+```
diff --git a/docs/setup/setting-up-buttons.md b/docs/setup/setting-up-buttons.md
@@ -26,6 +26,8 @@ plugins:
   - exporter-extras
 ```
 
+You can find the configuration reference [here](../reference/configuration/extras.md).
+
 ## Usage
 
 ### Adding a download button

diff --git a/docs/setup/setting-up-documents.md b/docs/setup/setting-up-documents.md
@@ -1,4 +1,4 @@
-# Setting up documents
+# Setting up PDF documents
 
 ## Prerequisites
 
@@ -32,6 +32,8 @@ plugins:
   - exporter-pdf
 ```
 
+You can find the configuration reference [here](../reference/configuration/pdf.md).
+
 ???+ question "Why multiple plugins?"
 
     **MkDocs Exporter** comes as various plugins in a single package.

diff --git a/mkdocs_exporter/plugin.py b/mkdocs_exporter/plugin.py
@@ -79,6 +79,6 @@ class DeprecatedPlugin(Plugin):
   def on_config(self, config: dict, **kwargs) -> None:
     """Invoked when the configuration has been loaded."""
 
-    logger.warning("The plugin name 'mkdocs/exporter' will stop working soon, please replace it with 'exporter'")
+    logger.warning("The plugin name 'mkdocs/exporter' has been deprecated, please replace it with 'exporter'")
 
     super().on_config(config, **kwargs)
diff --git a/mkdocs_exporter/plugins/extras/config.py b/mkdocs_exporter/plugins/extras/config.py
@@ -25,8 +25,5 @@ class Config(BaseConfig):
   enabled = c.Type(bool, default=True)
   """Is the plugin enabled?"""
 
-  downloads = c.ListOfItems(c.Choice(('pdf', 'html')), default=['pdf'])
-  """The download buttons to show."""
-
   buttons = c.ListOfItems(c.SubConfig(ButtonConfig))
   """The buttons to add."""
diff --git a/mkdocs_exporter/plugins/extras/plugin.py b/mkdocs_exporter/plugins/extras/plugin.py
@@ -53,6 +53,6 @@ class DeprecatedPlugin(Plugin):
   def on_config(self, *args, **kwargs) -> None:
     """Invoked when the configuration has been loaded."""
 
-    logger.warning("The plugin name 'mkdocs/exporter/extras' will stop working soon, please replace it with 'exporter-extras'")
+    logger.warning("The plugin name 'mkdocs/exporter/extras' has been deprecated, please replace it with 'exporter-extras'")
 
     super().on_config(*args, **kwargs)
diff --git a/mkdocs_exporter/plugins/pdf/plugin.py b/mkdocs_exporter/plugins/pdf/plugin.py
@@ -177,6 +177,6 @@ class DeprecatedPlugin(Plugin):
   def on_config(self, config: dict, **kwargs) -> None:
     """Invoked when the configuration has been loaded."""
 
-    logger.warning("The plugin name 'mkdocs/exporter/pdf' will stop working soon, please replace it with 'exporter-pdf'")
+    logger.warning("The plugin name 'mkdocs/exporter/pdf' has been deprecated, please replace it with 'exporter-pdf'")
 
     super().on_config(config, **kwargs)
diff --git a/mkdocs_exporter/themes/readthedocs/theme.py b/mkdocs_exporter/themes/readthedocs/theme.py
@@ -30,7 +30,10 @@ def button(self, preprocessor: Preprocessor, title: str, icon: str, attributes:
     button = preprocessor.html.new_tag('a', title=title, attrs={'class': 'btn btn-neutral float-right', **attributes})
     button.string = title
 
-    preprocessor.html.find('div', {'class': 'document'}).insert(0, button)
+    target = preprocessor.html.find('div', {'class': 'document'})
+
+    if target:
+      target.insert(0, button)
 
 
   def icon(self, name: str):