Port: Ensure build compatibility with Sphinx 8.x.x

Tested both with sphinx 7.4.7 and sphinx 8.1.3.

Signed-off-by: Nicolae Dicu <[email protected]>

Author: nicu1989

README.md

@@ -10,3 +10,110 @@ See [docs/](docs/) for more information.
 
 [pypi-badge]: https://img.shields.io/pypi/v/sphinx-rust.svg
 [pypi-link]: https://pypi.org/project/sphinx-rust
+
+## Fork notes
+
+### Integration, usage and testing
+
+**CURRENTLY FORK UNDER DEVELOPMENT! - PIP PACKAGE UNAVAILABLE**
+
+* In order to integrate in score:
+
+Update score/docs/conf.py :
+
+```python
+extensions = [
+    "sphinx_rust",
+    ...
+]
+
+# point to a rust crate in score(create a dummy one for testing if unavailable)
+rust_crates = [
+    "../rust-crates/dummy_crate",
+]
+```
+In index.rst :
+```
+Rust API <api/crates/dummy_crate/index>
+```
+
+* Testing in score repo:
+
+For fast development it is recomended to convert sphinx-rust module to bazel module by creating:
+
+- __sphinx-rust__/BUILD.bazel:
+
+```python
+load("@rules_python//python:defs.bzl", "py_library")
+
+py_library(
+    name = "sphinx_rust",
+    srcs = glob(["python/sphinx_rust/**/*.py"]),
+    data = glob([
+        "python/sphinx_rust/sphinx_rust.cpython-312-*.so",
+    ]),
+    imports = ["python"],
+    visibility = ["//visibility:public"],
+)
+```
+
+- __sphinx-rust__/MODULE.bazel
+
+```python
+module(name = "sphinx_rust", version = "0.0.0-dev")
+bazel_dep(name = "rules_python", version = "1.4.1")
+```
+
+Now we can add the __sphinx_rust__ module directly in __score__:
+
+- __score__/MODULE.bazel:
+
+```python
+bazel_dep(name = "sphinx_rust", version = "0.0.0-dev")
+local_path_override(module_name = "sphinx_rust", path = "../sphinx-rust")
+```
+
+- create the dummy_crate in __score__ with the following structure and content:
+
+```sh
+../score/rust-crates/
+└── dummy_crate
+    ├── Cargo.toml
+    └── src
+        └── lib.rs
+```
+
+Cargo.toml:
+
+```yaml
+[package]
+name = "dummy_crate"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+
+[lib]
+name = "dummy_crate"
+```
+
+lib.rs:
+
+```rs
+pub fn add(left: usize, right: usize) -> usize {
+    left + right
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn it_works() {
+        let result = add(2, 2);
+        assert_eq!(result, 4);
+    }
+}
+```

python/sphinx_rust/directives/_core.py

@@ -146,8 +146,11 @@ def parse_docstring(
         return []
 
     docstring = item.docstring if docstring is None else docstring
-    source_path = env.doc2path(  # TODO this actually should be the rust file path
-        env.docname
+
+    source_path = str(
+        env.doc2path(  # TODO this actually should be the rust file path
+            env.docname
+        )
     )
     # TODO how to handle line numbers?
     document = utils.new_document(source_path, doc.settings)