Merge pull request OPM#10 from hakonhagland/view_docs

Commands for viewing the documentation

Author: Lisa Julia Nebel

python/sphinx_docs/Makefile

@@ -1,7 +1,12 @@
-.PHONY: docs
+.PHONY: docs view-docs
+
+CURRENT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD)
+GIT_ROOT := $(shell git rev-parse --show-toplevel)
 
 # Build the documentation locally for the current branch
 # NOTE: You need to commit your changes before running this command
-CURRENT_BRANCH=$(shell git rev-parse --abbrev-ref HEAD)
 docs:
 	sphinx-versioned -m ${CURRENT_BRANCH} -b ${CURRENT_BRANCH} --git-root ../../
+
+view-docs:
+	@xdg-open "file://$(GIT_ROOT)/python/sphinx_docs/docs/_build/$(CURRENT_BRANCH)/index.html"

python/sphinx_docs/README.md

@@ -30,6 +30,9 @@ 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
+$ make docs
+# View the generated documentation for the current branch in the browser
+$ make view-docs
+# Or for a specific branch
+$ opmdoc-view-doc --branch=master
 ```

python/sphinx_docs/pyproject.toml

@@ -18,6 +18,7 @@ sphinx-versioned-docs = "^1.3.1"
 
 [tool.poetry.scripts]
 opmdoc-download-files = "opm_python_docs.download_files:main"
+opmdoc-view-doc = "opm_python_docs.view_docs:main"
 
 [build-system]
 requires = ["poetry-core"]

python/sphinx_docs/src/opm_python_docs/download_files.py

@@ -2,30 +2,15 @@
 
 import logging
 import requests
-import subprocess
-from pathlib import Path
 
 import click
 
+from opm_python_docs import helpers
+
 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_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: int) -> str:
     """Convert a PR number to a commit hash."""
@@ -49,7 +34,7 @@ def download_docstring_file(url: str, pr_number: int|None) -> 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
-    git_root_dir = get_git_root()
+    git_root_dir = helpers.get_git_root()
     save_path = git_root_dir / "python" / filename
     with open(str(save_path), "wb") as file:
         file.write(response.content)
@@ -60,7 +45,7 @@ def download_dune_module() -> None:
     logging.info("Downloading dune.module file")
     response = requests.get(URL_DUNE_MODULE)
     response.raise_for_status()
-    git_root_dir = get_git_root()
+    git_root_dir = helpers.get_git_root()
     save_path = git_root_dir / "dune.module"
     with open(save_path, "wb") as file:
         file.write(response.content)

python/sphinx_docs/src/opm_python_docs/helpers.py

@@ -0,0 +1,30 @@
+import subprocess
+from pathlib import Path
+
+def get_current_branch() -> str:
+    """Return the current Git branch."""
+    try:
+        output = subprocess.check_output(
+            ["git", "branch", "--show-current"],
+            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.")
+    return output.decode("utf-8").strip()
+
+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)

python/sphinx_docs/src/opm_python_docs/view_docs.py

@@ -0,0 +1,38 @@
+#! /usr/bin/env python3
+
+import logging
+
+import click
+
+from opm_python_docs import helpers
+
+
+# CLI command: opmdoc-view-doc
+#
+# SHELL USAGE:
+#
+#  opmdoc-view-doc --branch <branch>
+#
+# DESCRIPTION:
+#
+#  View the generated sphinx documentation for the given branch in the default browser.
+#  If the branch is not provided, the current git branch is used.
+#
+# EXAMPLES:
+#
+#  opmdoc-view-doc   # Opens index.html for the current git branch in the default browser
+#
+#
+#
+@click.command()
+@click.option("--branch", type=str, help="Branch to view documentation for. If not provided, the current git branch is used.")
+def main(branch: str|None) -> None:
+    logging.basicConfig(level=logging.INFO)
+    git_root_dir = helpers.get_git_root()
+    branch = branch or helpers.get_current_branch()
+    logging.info(f"Opening documentation for branch {branch}")
+    url = f"file://{git_root_dir}/python/sphinx_docs/docs/_build/{branch}/index.html"
+    click.launch(url)
+
+if __name__ == '__main__':
+    main()