Merge branch 'main' of https://github.com/yinchi/histopath-bim-des

README.md

@@ -8,23 +8,57 @@
 
 ## Developer Setup
 
+**VSCode and WSL2 (for Windows users)**
+
+It is recommended to work on this project using Visual Studio Code with WSL2, which provides a
+Linux environment on Windows. See
+[this tutorial](https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode) on
+how to set up VSCode and WSL2.
+
+**Cloning the repository**
+
+```bash
+git clone https://github.com/yinchi/histopath-bim-des.git
+cd histopath-bim-des
+
+# Open the newly cloned repo in VS Code
+code .
+```
+
+**Installing the project and its dependencies**
+
 This project uses the [Poetry](https://python-poetry.org/) package manager.
 To set up the project on your local computer, run:
 
 ```bash
+# Installs poetry system-wide 
+sudo apt install python3-poetry
+# optional
+poetry config virtualenvs.in-project true
+
 poetry install
 ```
 
 Other useful Poetry commands include `add`, `remove`, and `run`. As this project is not meant to
 be used as a library, the `build` and `publish` commands are not recommended.
 
-## docs.sh
+## scripts.sh
 
-`docs.sh` contains functions for Sphinx documentation. To use these, run the following in `bash`:
+`scripts.sh` contains functions for Sphinx documentation. To use these, run the following in `bash`:
 
 ```bash
-source docs.sh
+poetry shell
+
+# in the new bash subshell:
+
+source scripts.sh
 clean-docs  # reset the /docs directory
 build-docs
 serve-docs  # defaulting to port 8000
-```
+
+# use CTRL+D to exit to the base shell.
+```
+
+`scripts.sh` also provides `projroot()` for quickly changing to the root of the project directory,
+as well as adding `script/` to the `PATH` environment variable.
+

pyproject.toml

@@ -36,6 +36,7 @@ ipykernel = "^6.29.4"
 matplotlib = "^3.8.4"
 pylint = "^3.1.0"
 erdantic = "^1.0.2"
+gitpython = "^3.1.43"
 
 [tool.poetry.group.doc.dependencies]
 sphinx = "^7.3.7"

docs.sh → scripts.sh

@@ -21,3 +21,9 @@ serve-docs() {
     python -m http.server --directory docs/_build/html/
     popd
 }
+
+projroot() {
+    cd `git rev-parse --show-toplevel`
+}
+
+PATH=$PATH:`git rev-parse --show-toplevel`/scripts

scripts/webdoc.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+
+import os, sys
+import git
+
+# OPEN URL FROM SPHINX's CONF.PY `intersphinx_mapping`
+#
+# This script will open the Sphinx documentation for a
+# given Python library, if it is defined in the conf.py
+# file of a Sphinx project.  If no library is specified,
+# the contents of the `intersphinx_mapping` variable is
+# shown instead.
+
+def get_git_root(path):
+    git_repo = git.Repo(path, search_parent_directories=True)
+    git_root = git_repo.git.rev_parse("--show-toplevel")
+    return git_root
+
+mypath = get_git_root(os.getcwd())
+
+
+exec(open(f'{mypath}/docs/conf.py', 'r', encoding='utf-8').read())
+
+if len(sys.argv) == 1:
+    for k, v in intersphinx_mapping.items():
+        print(k, v[0])
+    print()
+
+else:
+    url = intersphinx_mapping.get(sys.argv[1], None)[0]
+    if url:
+        print(url)
+        os.system(f"xdg-open '{url}' >/dev/null 2>&1")
+    else:
+        print(f'{sys.argv[1]} not in intersphinx_mapping.')