From fea8cf3140018c4be452017c4b5cd4961276eb77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5kon=20H=C3=A6gland?= Date: Thu, 9 Jan 2025 15:09:15 +0100 Subject: [PATCH] Commands for viewing the documentation Added commands for viewing the generated documentation in the default browser --- python/sphinx_docs/Makefile | 9 ++++- python/sphinx_docs/README.md | 7 +++- python/sphinx_docs/pyproject.toml | 1 + .../src/opm_python_docs/download_files.py | 23 ++--------- .../src/opm_python_docs/helpers.py | 30 +++++++++++++++ .../src/opm_python_docs/view_docs.py | 38 +++++++++++++++++++ 6 files changed, 85 insertions(+), 23 deletions(-) create mode 100644 python/sphinx_docs/src/opm_python_docs/helpers.py create mode 100644 python/sphinx_docs/src/opm_python_docs/view_docs.py diff --git a/python/sphinx_docs/Makefile b/python/sphinx_docs/Makefile index 5315d96..086c2ed 100644 --- a/python/sphinx_docs/Makefile +++ b/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" diff --git a/python/sphinx_docs/README.md b/python/sphinx_docs/README.md index 24c2712..7b2c1bd 100644 --- a/python/sphinx_docs/README.md +++ b/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 ``` diff --git a/python/sphinx_docs/pyproject.toml b/python/sphinx_docs/pyproject.toml index 30111aa..79f5648 100644 --- a/python/sphinx_docs/pyproject.toml +++ b/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"] diff --git a/python/sphinx_docs/src/opm_python_docs/download_files.py b/python/sphinx_docs/src/opm_python_docs/download_files.py index 30f51c5..1c0925b 100755 --- a/python/sphinx_docs/src/opm_python_docs/download_files.py +++ b/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) diff --git a/python/sphinx_docs/src/opm_python_docs/helpers.py b/python/sphinx_docs/src/opm_python_docs/helpers.py new file mode 100644 index 0000000..5e610fd --- /dev/null +++ b/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) diff --git a/python/sphinx_docs/src/opm_python_docs/view_docs.py b/python/sphinx_docs/src/opm_python_docs/view_docs.py new file mode 100644 index 0000000..3796670 --- /dev/null +++ b/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 +# +# 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()