Move script to python folder

Author: hakonhagland

python/sphinx_docs/README.md

@@ -1,4 +1,4 @@
-# Python scripts for building opm-simulators sphinx documentation
+# Python scripts for building opm-simulators and opm-common sphinx documentation
 
 ## Installation of the python scripts
 - Requires python3 >= 3.10
@@ -21,3 +21,15 @@ $ python -m venv .venv
 $ source .venv/bin/activate
 $ pip install .
 ```
+
+### Scripts
+
+After installation, you can run the following scripts:
+
+```
+# Downloads docstrings JSON files and dune.module file before building the documentation locally
+$ opmdoc-download-files
+# Generate the documentation
+$ make
+# View the generated documentation in the browser
+```

python/sphinx_docs/docs/conf.py

@@ -34,7 +34,7 @@ def extract_opm_simulators_release():
 # opm.simulators.BlackOilSimulator Python module will also have access to the docstrings.)
 sys.path.insert(0, os.path.abspath("../src"))
 # Our sphinx extension that will use the docstrings.json file to generate documentation
-extensions = ["opm_simulators_docs.sphinx_ext_docstrings"]
+extensions = ["opm_python_docs.sphinx_ext_docstrings"]
 # Path to docstrings.json
 opm_simulators_docstrings_path = os.path.abspath('../../docstrings_simulators.json')
 opm_common_docstrings_path = os.path.abspath('../../docstrings_common.json')
@@ -50,7 +50,7 @@ def extract_opm_simulators_release():
 html_context = {
     "display_github": True,
     "github_user": "OPM",
-    "github_repo": "opm-simulators",
+    "github_repo": "opm-python-documentation",
     "github_version": "master",
     "conf_py_path": "/python/docs/",
 }

python/sphinx_docs/pyproject.toml

@@ -1,11 +1,11 @@
 [tool.poetry]
-name = "opm-simulators-docs"
+name = "opm-python-docs"
 version = "0.1.0"
 description = """Helper scripts for generating sphinx documentation for the \
-                 opm-simulators Python bindings"""
+                 opm-simulators and opm-common Python bindings"""
 authors = ["Håkon Hægland <hakon.hagland@gmail.com>"]
 readme = "README.md"
-packages = [{ include = "opm_simulators_docs", from = "src"}]
+packages = [{ include = "opm_python_docs", from = "src"}]
 license = "GPL3"
 repository = "https://github.com/OPM/opm-simulators"
 
@@ -16,6 +16,9 @@ sphinx-rtd-theme = "^1.3.0"
 click = "^8.1.7"
 sphinx-versioned-docs = "^1.3.1"
 
+[tool.poetry.scripts]
+opmdoc-download-files = "opm_python_docs.download_files:main"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"

scripts/download_files.py …cs/src/opm_python_docs/download_files.pyscripts/download_files.py renamed to python/sphinx_docs/src/opm_python_docs/download_files.py scripts/download_files.py renamed to python/sphinx_docs/src/opm_python_docs/download_files.py

@@ -2,17 +2,28 @@
 
 import logging
 import requests
+import subprocess
 from pathlib import Path
 
 URL_SIMULATORS = "https://raw.githubusercontent.com/OPM/opm-simulators/master/python/docstrings_simulators.json"
 URL_COMMON = "https://raw.githubusercontent.com/OPM/opm-common/master/python/docstrings_common.json"
 URL_DUNE_MODULE = "https://raw.githubusercontent.com/OPM/opm-simulators/master/dune.module"
 
-def get_script_dir():
-    """Return the directory of the script."""
-    script_path = Path(__file__).resolve()
-    script_dir = script_path.parent
-    return script_dir
+def get_git_root() -> Path:
+    """Return the absolute path of the opm-python-documentation repository's root."""
+    try:
+        output = subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            stderr=subprocess.STDOUT
+        )
+    except subprocess.CalledProcessError:
+        # Handle the error if we're not inside a Git repo, etc.
+        raise RuntimeError("Not a valid Git repository or other error occurred.")
+    # Check that the parent directory is the opm-python-documentation repository
+    root = output.decode("utf-8").strip()
+    if not root.endswith("opm-python-documentation"):
+        raise RuntimeError("Not in the opm-python-documentation repository.")
+    return Path(root)
 
 def convert_pr_to_commit_hash(repo: str, pr_number: str) -> str:
     """Convert a PR number to a commit hash."""
@@ -24,7 +35,6 @@ def convert_pr_to_commit_hash(repo: str, pr_number: str) -> str:
 
 def download_docstring_file(url: str) -> None:
     """Download a docstrings file from a URL (either opm-simulators or opm-common)."""
-    # Ask command line user question if to use master or PR branch
     if "opm-simulators" in url:
         repo = "opm-simulators"
         filename = "docstrings_simulators.json"
@@ -44,9 +54,9 @@ def download_docstring_file(url: str) -> None:
     logging.info(f"Downloading docstrings file from {url}")
     response = requests.get(url)
     response.raise_for_status()  # Raises 404 if the file is not found
-    script_dir = get_script_dir()
-    save_path = script_dir.parent / "python" / filename
-    with open(save_path, "wb") as file:
+    git_root_dir = get_git_root()
+    save_path = git_root_dir / "python" / filename
+    with open(str(save_path), "wb") as file:
         file.write(response.content)
     logging.info(f"Saved docstrings file to {save_path}")
 
@@ -55,17 +65,17 @@ def download_dune_module() -> None:
     logging.info("Downloading dune.module file")
     response = requests.get(URL_DUNE_MODULE)
     response.raise_for_status()
-    script_dir = get_script_dir()
-    save_path = script_dir.parent / "dune.module"
+    git_root_dir = get_git_root()
+    save_path = git_root_dir / "dune.module"
     with open(save_path, "wb") as file:
         file.write(response.content)
     logging.info(f"Saved dune.module file to {save_path}")
 
 def main() -> None:
+    logging.basicConfig(level=logging.INFO)
     download_docstring_file(URL_SIMULATORS)
     download_docstring_file(URL_COMMON)
     download_dune_module()
 
 if __name__ == '__main__':
-    logging.basicConfig(level=logging.INFO)
     main()