Improve project_root detection

Project root now detected by walking the parent paths looking for .git.
Can be overridden with new ``gitref_relative_project_root`` config
value.

Fixes #12

Author: radiac

Diff for: README.md

@@ -14,21 +14,17 @@ Key features:
 * Link to source code on github
 * Incorporate into tests or git hooks
 
-Supports Python 3.6+
+Supports Python 3.7+
 
 
-Installation
-============
+## Installation
 
 Install::
 
     pip install sphinx-gitref
 
 
-Modify your Sphinx ``conf.py``:
-
-1. Add ``sphinx_gitref`` to the ``extensions`` list in your Sphinx ``conf.py``:
-
+In your Sphinx ``conf.py``, add ``sphinx_gitref`` to the ``extensions`` list:
 
    ```python
    extensions = [
@@ -37,35 +33,9 @@ Modify your Sphinx ``conf.py``:
    ]
    ```
 
-2. Optional: Explicitly specify the remote URL.
-
-   Gitref will try to detect your remote origin URL from the ``.git`` dir in your docs'
-   parent dir. If it can't find it, or detects the wrong remote, you can set or override
-   the remote URL explicitly with::
-
-   ```python
-   gitref_remote_url = "https://github.com/username/repository.git"
-   ```
-
-3. Optional: Explicitly specify the branch to link to.
-
-   Gitref will try to detect your current branch from the ``.git`` dir in your docs'
-   parent dir. If it can't find it, or you'd like it to use a different branch, you can
-   set or override it explicitly with::
-
-   ```python
-   gitref_branch = "master"
-   ```
-
-4. Optional: Change the link label format when a coderef is provided without an
-   explicit label, eg `` :gitref:`filename.py::coderef` ``
+Gitref should now work for most projects, but see "Configuration" below to customise its
+defaults.
 
-   Gitref defaults to using showing the coderef and dropping the filename. This can be
-   overridden by setting a format string::
-
-   ```python
-   gitref_label_format = "{filename} {coderef}"
-   ```
 
 ## Usage
 
@@ -131,9 +101,71 @@ class Gitea(Remote):
 ```
 
 
+## Configuration
+
+Define the following variables in Sphinx ``conf.py``.
+
+
+### ``gitref_relative_project_root``
+
+Explicitly specify the relative path to the project root form your docs' source dir.
+
+The project root is the root directory of your git repository.
+
+Gitref will walk up the directory tree from your documentation source, looking for the
+first directory with a ``.git`` dir. It will use this as the project root.
+
+If it mis-detects the path, you can configure it with a relative path. For example, if
+your docs are in ``docs/``, you can specify one parent up as:
+
+```python
+gitref_relative_project_root = ".."
+```
+
+
+### ``gitref_remote_url``
+
+Explicitly specify the remote URL.
+
+Gitref will try to detect your remote origin URL from the ``.git`` dir in your project
+root. If it can't find it, or detects the wrong remote, you can set or override the
+remote URL explicitly with:
+
+```python
+gitref_remote_url = "https://github.com/username/repository.git"
+```
+
+
+### ``gitref_branch``
+
+Explicitly specify the branch to link to.
+
+Gitref will try to detect your current branch from the ``.git`` dir in your project
+root. If it can't find it, or you'd like it to use a different branch, you can set or
+override it explicitly with::
+
+```python
+gitref_branch = "master"
+```
+
+### ``gitref_label_format``
+
+Change the link label format when a coderef is provided without an explicit label, eg
+`` :gitref:`filename.py::coderef` ``
+
+Gitref defaults to using showing the coderef and dropping the filename. This can be
+overridden by setting a format string::
+
+```python
+gitref_label_format = "{filename} {coderef}"
+```
+
+
+
 ## Changelog
 
 0.3.0 - 2024-05-19
+* Better project root detection with override support (fixes #12)
 * Support latest Sphinx
 
 0.2.1 - 2022-02-19

Diff for: pyproject.toml

@@ -18,7 +18,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 keywords = ["django"]
-requires-python = ">=3.6"
+requires-python = ">=3.7"
 dependencies = [
     "docutils",
     "sphinx",

Diff for: sphinx_gitref/role.py

@@ -1,16 +1,57 @@
 """
 Sphinx role
 """
+from __future__ import annotations
+
+from functools import lru_cache
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from docutils import nodes, utils
 from sphinx.util.nodes import split_explicit_title
 
 from .exceptions import ParseError
 from .parser import python_to_lineno
 
+if TYPE_CHECKING:
+    from docutils.parsers.rst.states import Inliner
+
 
-def gitref(name, rawtext, text, lineno, inliner, options={}, content=[]):
+@lru_cache
+def get_project_root(doc_root: Path, option: str | None):
+    # See if gitref_relative_project_root has told us where to look
+    if option is not None:
+        project_root = (doc_root / option).absolute()
+        if not project_root.is_dir():
+            raise ValueError(
+                f"Project root {project_root} does not exist"
+                " - check your gitref_relative_project_root"
+            )
+        return project_root
+
+    # Try to detect it
+    project_root = doc_root
+    while project_root != project_root.parent:
+        if (project_root / ".git").is_dir():
+            return project_root
+        project_root = project_root.parent
+
+    # Couldn't find it
+    raise ValueError(
+        "Could not find ancestor path containing a .git dir"
+        " - configure with gitref_relative_project_root"
+    )
+
+
+def gitref(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: Inliner,
+    options: dict | None = None,
+    content=[],
+):
     """
     Reference a file in git
 
@@ -40,9 +81,9 @@ def gitref(name, rawtext, text, lineno, inliner, options={}, content=[]):
     except AttributeError:
         raise ValueError("Config does not specify gitref_remote")
 
-    # Assume the project root is one dir up from the docs dir
-    doc_root = inliner.document.settings.env.srcdir
-    project_root = Path(doc_root).parent
+    # Assume the project root is the first ancestor dir from docs to contain a .git dir
+    doc_root = Path(inliner.document.settings.env.srcdir)
+    project_root = get_project_root(doc_root, app.config.gitref_relative_project_root)
 
     # Process text value
     has_t, title, target = split_explicit_title(text)
@@ -83,5 +124,5 @@ def gitref(name, rawtext, text, lineno, inliner, options={}, content=[]):
 
     ref = remote.get_url(filename=filename, line=ref_start)
 
-    node = nodes.reference(rawtext, title, refuri=ref, **options)
+    node = nodes.reference(rawtext, title, refuri=ref, **(options or {}))
     return [node], []

Diff for: sphinx_gitref/setup.py

@@ -42,6 +42,7 @@ def setup(app):
     repo = Repo(git_root)
 
     # Add config variables
+    app.add_config_value("gitref_relative_project_root", default=None, rebuild="html")
     app.add_config_value("gitref_remote_url", repo.get_remote_url(), "html")
     app.add_config_value("gitref_branch", repo.get_local_branch(), "html")
     app.add_config_value("gitref_label_format", DEFAULT_LABEL_FORMAT, "html")