Merge pull request #7 from pappasam/add-docs

Add docs

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.18.0
+
+### Added
+
+- In-depth documentation. Lots of docstring updates!
+- `serdelicacy.SerdeError` as part of the public API (mostly for documentation)
+
 ## 0.17.0
 
 ### Added

Makefile

@@ -5,7 +5,7 @@ help:  ## Print this help menu
 
 .PHONY: setup
 setup:  ## Set up the local development environment
-	poetry install -E tox
+	poetry install -E docs
 	poetry run pre-commit install
 
 .PHONY: tox
@@ -16,3 +16,17 @@ test:  ## Run the tests
 publish:  ## Build & publish the new version
 	poetry build
 	poetry publish
+
+.PHONY: build-docs
+build-docs:
+	poetry run sphinx-build -M html docs docs/_build
+
+.PHONY: serve-docs
+serve-docs: build-docs  ## Simple development server for Sphinx docs
+	@echo "Serving documentation locally."
+	@echo "Open browser with 'make open-docs'"
+	@find docs serdelicacy | entr -ps "$(MAKE) build-docs"
+
+.PHONY: open-docs
+open-docs:  ## Open Sphinx docs index in a browser
+	gio open docs/_build/html/index.html

docs/conf.py

@@ -0,0 +1,84 @@
+"""Configuration file for the Sphinx documentation builder."""
+
+import toml
+
+with open("../pyproject.toml") as infile:
+    pyproject = toml.load(infile)
+
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# pylint: disable=invalid-name
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- Project information -----------------------------------------------------
+
+project = "serdelicacy"
+copyright = "2020, Samuel Roeca"  # pylint: disable=redefined-builtin
+author = "Samuel Roeca"
+
+# The full version, including alpha/beta/rc tags
+release = pyproject["tool"]["poetry"]["version"]
+
+# -- General configuration ---------------------------------------------------
+master_doc = "index"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "m2r2",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+source_suffix = [".rst", ".md"]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "canonical_url": "",
+    "analytics_id": "",  #  Provided by Google in your dashboard
+    "logo_only": False,
+    "display_version": True,
+    "prev_next_buttons_location": "bottom",
+    "style_external_links": False,
+    "style_nav_header_background": "#2980B9",
+    # Toc options
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ["_static"]
+
+# -- Autodoc information ---------------------------------------------------
+autodoc_typehints = "description"

docs/index.rst

@@ -0,0 +1,9 @@
+.. toctree::
+    :maxdepth: 3
+    :caption: Table of Contents
+    :hidden:
+
+    public_api
+    Git Repository <https://github.com/pappasam/serdelicacy>
+
+.. mdinclude:: ../README.md

docs/public_api.rst

@@ -0,0 +1,88 @@
+##########
+Public API
+##########
+
+.. automodule:: serdelicacy
+
+Deserialization
+===============
+
+This function is the entrypoint to `serdelicacy`'s deserialization process:
+
+.. autofunction:: serdelicacy.load
+
+Serialization
+=============
+
+This function is the entrypoint to `serdelicacy`'s serialization process:
+
+.. autofunction:: serdelicacy.dump
+
+Utilities
+=========
+
+You may use the following tools to:
+
+1. Operate on `serdelicacy`-affecred Python values in a typesafe way
+2. Augment `dataclasses.dataclass` to give `serdelicacy` more information about how to process data.
+
+.. autofunction:: serdelicacy.get
+
+.. autofunction:: serdelicacy.is_missing
+
+.. autoclass:: serdelicacy.Override
+
+Types
+=====
+
+The following types are custom to `serdelicacy`:
+
+.. autodata:: serdelicacy.OptionalProperty
+
+   **Example**
+
+   .. code-block:: python
+
+       from typing import List, Optional
+       from dataclasses import dataclass
+       import serdelicacy
+       from serdelicacy import OptionalProperty
+
+       DATA = [
+           {
+               "hello": "friend",
+               "world": "foe",
+           },
+           {
+               "hello": "Rawr",
+           },
+           {
+               "hello": None,
+               "world": "hehe",
+           },
+       ]
+
+       @dataclass
+       class HelloWorld:
+           hello: Optional[str]
+           world: OptionalProperty[str]
+
+       PARSED = serdelicacy.load(DATA, List[HelloWorld])
+
+       assert serdelicacy.is_missing(PARSED[1].world)
+       assert not PARSED[1].world  # note: it's Falsey!
+       assert PARSED[2].hello is None
+
+Exceptions
+==========
+
+`serdelicacy` may raise the following Python exceptions during the serialization and/or the deserialization process.
+
+.. autoexception:: serdelicacy.SerdeError
+    :show-inheritance:
+
+.. autoexception:: serdelicacy.DeserializeError
+    :show-inheritance:
+
+.. autoexception:: serdelicacy.SerializeError
+    :show-inheritance: