Add instructions for generating documentation (MIT-LCP#361)

cx1111 · web-flow · commit defb4e68202b · 2022-05-02T08:13:38.000-07:00
* Add Sphinx to dependencies

* Add document building workflow

* Add a requirements.txt file for readthedocs

* Add a warning for the major v4 breaking changes
diff --git a/.github/workflows/run-tests.yml b/.github/workflows/run-tests.yml
@@ -61,3 +61,16 @@ jobs:
       - name: Run tests
         run: |
           pytest-3
+
+  build-documentation:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,17 @@
+# File: .readthedocs.yaml
+
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.9"
+
+# Build from the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Explicitly set the version of Python and its requirements
+python:
+  install:
+    - requirements: docs/requirements.txt
diff --git a/README.md b/README.md
@@ -7,6 +7,13 @@
 [![PhysioNet Project](https://img.shields.io/badge/DOI-10.13026%2Fegpf--2788-blue)](https://doi.org/10.13026/egpf-2788)
 [![Supported Python Versions](https://img.shields.io/pypi/pyversions/wfdb.svg)](https://pypi.org/project/wfdb)
 
+## v4 Announcement
+
+[Major breaking changes](https://github.com/MIT-LCP/wfdb-python/issues/369) are planned for WFDB v4, in the core APIs, and the installation method. The planned release date is in August 2022.
+
+- Stable v3 documentation: <https://wfdb.readthedocs.io/en/stable/>
+- WIP v4 documentation: <https://wfdb.readthedocs.io/en/latest/>
+
 ## Introduction
 
 A Python-native package for reading, writing, processing, and plotting physiologic signal and annotation data. The core I/O functionality is based on the Waveform Database (WFDB) [specifications](https://github.com/wfdb/wfdb-spec/).
@@ -80,6 +87,20 @@ To upload a new distribution to PyPI:
 poetry publish
 ```
 
+### Creating Documentation
+
+The project's documentation is generated by [Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html) using the content in the [docs](./docs) directory. The generated content is then hosted on readthedocs (RTD) at: <http://wfdb.readthedocs.io>
+
+To manage the content on RTD, request yourself to be added to the [wfdb](https://readthedocs.org/projects/wfdb/) project. The project has already been configured to import content from the GitHub repository. Documentation for new releases should be automatically built and uploaded. See the [import guide](https://docs.readthedocs.io/en/stable/intro/import-guide.html) for more details.
+
+There is some redundancy in specifying the Sphinx requirements between pyproject.toml and [docs/requirements.txt](./docs/requirements.txt), the latter of which is used by RTD. Make sure that the content is consistent across the two files.
+
+To generate the HTML content locally, install the required dependencies and run from the `docs` directory:
+
+```sh
+make html
+```
+
 ### Tests
 
 Run tests using pytest:
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+sphinx==4.5.0
+sphinx_rtd_theme==1.0.0
+readthedocs-sphinx-search==0.1.1
diff --git a/pyproject.toml b/pyproject.toml
@@ -16,9 +16,10 @@ pytest = {version = "^7.1.1", optional = true}
 pytest-xdist = {version = "^2.5.0", optional = true}
 pylint = {version = "^2.13.7", optional = true}
 black = {version = "^22.3.0", optional = true}
+Sphinx = {version = "^4.5.0", optional = true}
 
 [tool.poetry.extras]
-dev = ["pytest", "pytest-xdist", "pylint", "black"]
+dev = ["pytest", "pytest-xdist", "pylint", "black", "Sphinx"]
 
 # Do NOT use [tool.poetry.dev-dependencies]. See: https://github.com/python-poetry/poetry/issues/3514
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+sphinx==4.5.0`
	`2`	`+sphinx_rtd_theme==1.0.0`
	`3`	`+readthedocs-sphinx-search==0.1.1`