feat: add type hints (#161)

stardog-union · Jul 12, 2023 · 092a485 · 092a485
1 parent e1ee5a6
commit 092a485
Show file tree

Hide file tree

Showing 9 changed files with 936 additions and 886 deletions.
diff --git a/README.md b/README.md
@@ -69,6 +69,67 @@ The docs can be built locally using [Sphinx](https://www.sphinx-doc.org/en/maste
   make html
   ```
 
+#### Autodoc Type Hints
+
+The docs use [`sphinx-autodoc-typehints`](https://github.com/tox-dev/sphinx-autodoc-typehints) which allows you to omit types when documenting argument/returns types of functions. For example:
+
+The following function:
+
+```python
+def database(self, name: str) -> "Database":
+    """Retrieves an object representing a database.
+
+    :param name: The database name
+
+    :return: the database
+    """
+    return Database(name, self.client)
+```
+
+will yield the following documentation after Sphinx processes it:
+
+![sphinx-autobuild-example](https://github.com/stardog-union/pystardog/assets/23270779/f0defa61-e0d5-4df6-9daf-6842e41a3889)
+
+> **Note**
+> Only arguments that have an existing `:param:` directive in the docstring get their
+> respective `:type:` directives added. The `:rtype:` directive is added if and only if no existing `:rtype:` is found.
+> See the [docs](https://github.com/tox-dev/sphinx-autodoc-typehints) for additional information on how the extension works.
+
+#### Auto Build 
+
+Docs can be rebuilt automatically when saving a Python file by utilizing [`sphinx-autobuild`](https://github.com/executablebooks/sphinx-autobuild)
+
+```shell
+cd docs
+pip install -r requirements.txt requirements-dev.txt
+make livehtml
+```
+
+This should make the docs available at [http://localhost:8000](http://localhost:8000).
+
+Example output after running `make livehtml`:
+
+```text
+❯ make livehtml
+sphinx-autobuild "." "_build"   --watch ../stardog/
+[sphinx-autobuild] > sphinx-build /Users/frodo/projects/pystardog/docs /Users/frodo/projects/pystardog/docs/_build
+Running Sphinx v6.2.1
+loading pickled environment... done
+building [mo]: targets for 0 po files that are out of date
+writing output...
+building [html]: targets for 0 source files that are out of date
+updating environment: 0 added, 0 changed, 0 removed
+reading sources...
+looking for now-outdated files... none found
+no targets are out of date.
+build succeeded.
+
+The HTML pages are in _build.
+[I 230710 15:26:18 server:335] Serving on http://127.0.0.1:8000
+[I 230710 15:26:18 handlers:62] Start watching changes
+[I 230710 15:26:18 handlers:64] Start detecting changes
+```
+
 ## Contributing and Development
 
 Contrbutions are always welcome to pystardog.

diff --git a/docs/Makefile b/docs/Makefile
@@ -16,4 +16,7 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --watch ../stardog/
diff --git a/docs/conf.py b/docs/conf.py
@@ -40,6 +40,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
@@ -185,5 +186,8 @@
 
 # -- Extension configuration -------------------------------------------------
 
+# sphinx_autodoc_typehints
+typehints_defaults = "comma"
+
 # Napoleon settings
 napoleon_numpy_docstring = False
diff --git a/docs/requirements-dev.txt b/docs/requirements-dev.txt
@@ -0,0 +1 @@
+sphinx-autobuild==2021.3.14
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 Sphinx==6.2.1
 sphinx-rtd-theme==1.2.2
+sphinx-autodoc-typehints==1.23.0
 contextlib2==21.6.0
 requests-toolbelt==0.9.1
 recommonmark==0.5.0