feat: allow file:// url schemes

README.md

@@ -107,6 +107,25 @@ Then you can use a Sphinx substitution with your application name to refer to it
 .. screenshot:: |example|/hello
 ```
 
+## Local files
+`sphinxcontrib-screenshot` supports opening local files with the `file://` URL scheme.
+
+```rst
+.. screenshot:: file:///path/to/my/project/index.html
+```
+
+You can also dynamically build the path where your files are stored by defining Sphinx substitutions in your configuration file:
+
+```python
+import pathlib
+root = pathlib.Path(__file__).parent.resolve().as_uri()
+rst_prolog = f".. |root| replace:: {root}"
+```
+
+```rst
+.. screenshot:: |root|/index.html
+```
+
 ## Local http server
 `sphinxcontrib-screenshot` supports URLs with the HTTP and HTTPS protocols.
 To take screenshots of local files and build the document while running a local server for them, you can use the NPM library [concurrently](https://www.npmjs.com/package/concurrently) in the following way:

sphinxcontrib/screenshot.py

@@ -175,9 +175,9 @@ def run(self) -> typing.List[nodes.Node]:
     pdf = 'pdf' in self.options
     interactions = '\n'.join(self.content)
 
-    if urlparse(url).scheme not in {'http', 'https'}:
+    if urlparse(url).scheme not in {'http', 'https', 'file'}:
       raise RuntimeError(
-          f'Invalid URL: {url}. Only HTTP/HTTPS URLs are supported.')
+          f'Invalid URL: {url}. Only HTTP/HTTPS/FILE URLs are supported.')
 
     # Generate filename based on hash of parameters
     hash_input = f'{url}_{height}_{width}_{color_scheme}_{interactions}'

tests/roots/test-color-schemes/conf.py

@@ -12,9 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 import pathlib
-import sys
-
-sys.path.insert(0, str(pathlib.Path(__file__).parent.resolve()))
 
 extensions = ['sphinxcontrib.screenshot']
-screenshot_apps = {"example": "example_app:create_app"}
+
+root = pathlib.Path(__file__).parent.resolve().as_uri()
+rst_prolog = f".. |root| replace:: {root}"

tests/roots/test-color-schemes/index.rst

@@ -1,4 +1,4 @@
-.. screenshot:: |example|
+.. screenshot:: |root|/index.html
    :width: 800
    :height: 600
    :color-scheme: dark