Improve documentation

- Switch to Read the Docs theme
- Include project README in docs homepage
- Move documentation of login environment variables from hidden logging
  to docstring and README.

Author: daviewales

README.md

@@ -5,7 +5,7 @@ can use it to automate uploads and downloads to the PMHC portal.
 
 ## Install
 
-This script is setup as a Python package. You should be able to install
+`pmhclib` is a Python package. You should be able to install
 it directly with `pip` or `poetry`:
 
 ``` sh
@@ -20,6 +20,15 @@ poetry add pmhclib@git+https://github.com/swsphn/pmhclib.git
 
 This will install `pmhclib` as an importable Python library.
 
+NOTE: This package depends on [Playwright][] to authenticate to the PMHC
+portal. Once the package is installed, you will need to install
+a browser for Playwright to use. Make sure you are in the same Python
+environment in which you installed `pmhclib`, then run:
+
+```
+playwright install chromium
+```
+
 ## Usage
 
 `pmhclib.PMHC` is intended to be used with a context manager. This
@@ -45,11 +54,55 @@ PMHC_PASSWORD
 
 Otherwise, you will be prompted for credentials interactively.
 
+In PowerShell, you can set the environment variables interactively as
+follows:
+
+``` ps1
+$env:PMHC_USERNAME='your_username_here'
+$env:PMHC_PASSWORD=python -c 'import getpass; print(getpass.getpass())'
+```
+
+In a Unix shell (Mac, Linux), you can do:
+
+``` bash
+export PMHC_USERNAME='your_username_here'
+read -rs PMHC_PASSWORD && export PMHC_PASSWORD
+```
+
 ## Documentation
 
+See the [online documentation][docs].
+
+### Built-in docs
+
 Review the built-in documentation from Python as follows:
 
 ``` python
 >>> from pmhclib import PMHC
 >>> help(PMHC)
 ```
+
+### Build docs
+
+You can also generate html documentation locally using [Sphinx][] if you
+have a local copy of the repository.
+
+Linux:
+
+```
+cd docs
+make html
+```
+
+PowerShell:
+
+```
+cd docs
+./make.bat html
+```
+
+The generated documentation can be viewed at `docs/_build/html/index.html`.
+
+[Playwright]: https://playwright.dev/python/
+[Sphinx]: https://www.sphinx-doc.org/
+[docs]: https://reimagined-doodle-o4zv319.pages.github.io/

docs/conf.py

@@ -23,7 +23,7 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
 # -- Options for autoapi

docs/index.md

@@ -0,0 +1,10 @@
+```{include} ../README.md
+```
+
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+autoapi/index
+```
+

docs/index.rst

@@ -15,8 +15,9 @@ playwright = ">=1.40.0"
 
 [tool.poetry.group.docs.dependencies]
 sphinx = ">=7.0.0"
-myst-parser = "^2.0.0"
-sphinx-autoapi = "^3.0.0"
+myst-parser = ">=2.0.0"
+sphinx-autoapi = ">=3.0.0"
+sphinx-rtd-theme = ">=2.0.0"
 
 [build-system]
 requires = ["poetry-core"]

pyproject.toml

@@ -118,31 +118,18 @@ def __init__(self, headless: bool = True):
     def login(self):
         """Logs in to PMHC website. This allows us to reuse the login the session
         across other class methods.
+
+        Set the following environment variables to skip interactive login prompt:
+
+        - `PMHC_USERNAME`
+        - `PMHC_PASSWORD`
         """
 
         # Prompt user for credentials if not set in env.
         username = os.getenv("PMHC_USERNAME")
         password = SecureString(os.getenv("PMHC_PASSWORD") or "")
 
         while not username:
-            if platform.system() == "Windows":
-                logging.debug(
-                    "In future, consider setting the following environment variables "
-                    "when running this script:\n"
-                    "PMHC_USERNAME and PMHC_PASSWORD\n"
-                    "To do so, run the following commands in PowerShell:\n"
-                    "$env:PMHC_USERNAME='your_username_here'\n"
-                    "$env:PMHC_PASSWORD=python -c 'import getpass; print(getpass.getpass())'"
-                )
-            elif platform.system() == "Linux":
-                logging.debug(
-                    "In future, consider setting the following environment variables "
-                    "when running this script:\n"
-                    "PMHC_USERNAME and PMHC_PASSWORD\n"
-                    "To do so, run the following commands in Linux:\n"
-                    "read PMHC_USERNAME && export PMHC_USERNAME\n"
-                    "read -rs PMHC_PASSWORD && export PMHC_PASSWORD"
-                )
             username = input("Enter PMHC username: ")
 
         while not password: