WIP Docs Experiment with Properdocs and Copy Clipboard

Experiment with Properdocs as a substitute for the troubled Mkdocs package. Alternate approach to PR #4971.

Also add javascript for copy-to-clipboard functionality for readthedocs and mkdocs themes. A little less aesthetic than material themes, but it should work.

Still unable to add dark mode to readthedocs theme.

.readthedocs..mkdocs.yaml

@@ -0,0 +1,12 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3"
+
+mkdocs:
+    configuration: mkdocs.mkdocs.yml

.readthedocs..readthedocs.yaml

@@ -0,0 +1,12 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+    os: ubuntu-22.04
+    tools:
+        python: "3"
+
+mkdocs:
+    configuration: mkdocs.readthedocs.yml

.readthedocs.properdocs.yaml

@@ -0,0 +1,14 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+    os: ubuntu-24.04
+    tools:
+        python: "3"
+    commands:
+        # 1. Install ProperDocs and any required themes/plugins
+        - pip install properdocs properdocs_theme_readthedocs properdocs_theme_mkdocs
+        # 2. Build the static site using the properdocs executable
+        - properdocs build --clean --site-dir $READTHEDOCS_OUTPUT/html

.readthedocs.yaml

@@ -4,9 +4,11 @@
 version: 2
 
 build:
-    os: ubuntu-22.04
+    os: ubuntu-24.04
     tools:
         python: "3"
-
-mkdocs:
-    configuration: mkdocs.yml
+    commands:
+        # 1. Install ProperDocs and any required themes/plugins
+        - pip install properdocs properdocs_theme_readthedocs properdocs_theme_mkdocs
+        # 2. Build the static site using the properdocs executable
+        - properdocs build --clean --site-dir $READTHEDOCS_OUTPUT/html

docs/extra/copyclipboard.css

@@ -0,0 +1,23 @@
+/* Style the injected copy button inside code wrappers */
+
+.copy-code-button {
+    position: absolute;
+    top: 5px;
+    right: 5px;
+    padding: 4px 8px;
+    font-size: 12px;
+    color: #333;
+    background-color: #f0f0f0;
+    border: 1px solid #ccc;
+    border-radius: 3px;
+    cursor: pointer;
+    opacity: 0.7;
+    transition: opacity 0.2s ease-in-out;
+    z-index: 10;
+}
+
+.copy-code-button:hover {
+    opacity: 1;
+    background-color: #e0e0e0;
+}
+

docs/extra/copyclipboard.js

@@ -0,0 +1,35 @@
+document.addEventListener("DOMContentLoaded", function () {
+    // Locate all code blocks inside the theme highlights
+    const codeBlocks = document.querySelectorAll("pre");
+
+    codeBlocks.forEach(function (block) {
+        // Create the button element
+        const button = document.createElement("button");
+        button.className = "copy-code-button";
+        button.type = "button";
+        button.innerText = "Copy";
+
+        // Extract raw code text from the pre/code block
+        const pre = block;
+        const code = pre.getElementsByTagName('code');
+        if (code.length == 1) {
+            button.addEventListener("click", function () {
+                const textToCopy = code[0].innerText || code[0].textContent;
+
+                navigator.clipboard.writeText(textToCopy).then(function () {
+                    button.innerText = "Copied!";
+                    setTimeout(function () {
+                        button.innerText = "Copy";
+                    }, 2000);
+                }).catch(function (error) {
+                    button.innerText = "Error";
+                    console.error("Failed to copy text: ", error);
+                });
+            });
+
+            // Append the button into the container block
+            block.setAttribute("style", "position: relative;");
+            block.appendChild(button);
+        }
+    });
+});

docs/extra/extrajs.js

@@ -2,4 +2,4 @@ document.addEventListener("DOMContentLoaded", function() {
   document.querySelectorAll("table").forEach(function(table) {
     table.classList.add("docutils");
   });
-});
+});

docs/index.md

@@ -2,7 +2,7 @@
 
 ![Logo](./assets/logo.svg)
 
-PhpSpreadsheet is a library written in pure PHP and offers a set of classes that
+[PhpSpreadsheet](https://www.github.com/PhpOffice/PhpSpreadsheet) is a library written in pure PHP and offers a set of classes that
 allow you to read and write various spreadsheet file formats such as Excel and LibreOffice Calc.
 
 ## File formats supported
@@ -27,7 +27,7 @@ Note - reading or writing certain aspects of a spreadsheet may not be supported
 
 ## Software requirements
 
-PHP version 8.1 or newer to develop using PhpSpreadsheet. Other requirements, such as PHP extensions, are enforced by
+PHP version 8.2 or newer to develop using PhpSpreadsheet. Other requirements, such as PHP extensions, are enforced by
 composer. See the `require` section of [the composer.json file](https://github.com/PHPOffice/PhpSpreadsheet/blob/master/composer.json)
 for details.
 
@@ -36,7 +36,7 @@ for details.
 LTS: Support for PHP versions will only be maintained for a period of six months beyond the
 [end of life of that PHP version](https://www.php.net/eol.php).
 
-Currently, the required PHP minimum version is __PHP 8.1__, and we [will support that version](https://www.php.net/eol.php) until June 2026.
+Currently, the required PHP minimum version is __PHP 8.2__, and we [will support that version](https://www.php.net/eol.php) until June 2027.
 
 Support for PHP versions will only be maintained for a period of six months beyond the
 [end of life](https://www.php.net/supported-versions) of that PHP version.
@@ -88,7 +88,7 @@ or the appropriate PDF Writer wrapper for the library that you have chosen to in
 
 #### Chart Export
 
-For Chart export, we support following packages, which you will also need to install yourself using `composer require`
+For Chart export, we support following packages, which you will also need to install yourself using `composer require`:
 - [jpgraph/jpgraph](https://packagist.org/packages/jpgraph/jpgraph) (this package was abandoned at version 4.0.
   You can manually download the latest version that supports PHP 8 and above from [jpgraph.net](https://jpgraph.net/))
 - [mitoteam/jpgraph](https://packagist.org/packages/mitoteam/jpgraph) - up to date fork with modern PHP versions support and some bugs fixed.
@@ -137,7 +137,9 @@ php -S localhost:8000 -t vendor/phpoffice/phpspreadsheet/samples
 
 Then point your browser to:
 
-> http://localhost:8000/
+```
+http://localhost:8000/
+```
 
 The samples may also be run directly from the command line, for example:
 

mkdocs.mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: PhpSpreadsheet Documentation
+#site_url: https://github.com/PHPOffice/phpspreadsheet
+repo_url: https://github.com/PHPOffice/phpspreadsheet
+#repo_name: PhpSpreadsheet
+#edit_uri: edit/master/docs/
+
+theme:
+  name: mkdocs
+  color_mode: auto               # Options: light, dark, or auto
+  user_color_mode_toggle: true    # Adds a button for users to switch manually
+extra_css:
+    - extra/extra.css
+    - extra/copyclipboard.css
+extra_javascript:
+    - extra/extrajs.js
+    - extra/copyclipboard.js
+markdown_extensions:
+    - md_in_html

mkdocs.readthedocs.yml

@@ -0,0 +1,16 @@
+site_name: PhpSpreadsheet Documentation
+#site_url: https://github.com/PHPOffice/phpspreadsheet
+repo_url: https://github.com/PHPOffice/phpspreadsheet
+#repo_name: PhpSpreadsheet
+#edit_uri: edit/master/docs/
+
+theme:
+  name: readthedocs
+extra_css:
+    - extra/extra.css
+    - extra/copyclipboard.css
+extra_javascript:
+    - extra/extrajs.js
+    - extra/copyclipboard.js
+markdown_extensions:
+    - md_in_html

mkdocs.yml

@@ -1,11 +1,16 @@
 site_name: PhpSpreadsheet Documentation
+#site_url: https://github.com/PHPOffice/phpspreadsheet
 repo_url: https://github.com/PHPOffice/phpspreadsheet
-edit_uri: edit/master/docs/
+#repo_name: PhpSpreadsheet
+#edit_uri: edit/master/docs/
 
-theme: readthedocs
+theme:
+  name: readthedocs
 extra_css:
     - extra/extra.css
+    - extra/copyclipboard.css
 extra_javascript:
     - extra/extrajs.js
+    - extra/copyclipboard.js
 markdown_extensions:
     - md_in_html

properdocs.yml

@@ -0,0 +1,18 @@
+site_name: PhpSpreadsheet Documentation
+#site_url: https://github.com/PHPOffice/phpspreadsheet
+repo_url: https://github.com/PHPOffice/phpspreadsheet
+#repo_name: PhpSpreadsheet
+#edit_uri: edit/master/docs/
+
+theme: 
+  name: readthedocs
+  color_mode: auto               # Options: light, dark, or auto
+  user_color_mode_toggle: true    # Adds a button for users to switch manually
+extra_css:
+    - extra/extra.css
+    - extra/copyclipboard.css
+extra_javascript:
+    - extra/extrajs.js
+    - extra/copyclipboard.js
+markdown_extensions:
+    - md_in_html