add initial docs

These are fresh docs just to get people oriented:

    make -C doc html

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

.gitignore

@@ -4,3 +4,4 @@ build/
 devicetree.egg-info/
 __pycache__/
 .tox/
+doc/build/

doc/Makefile

@@ -0,0 +1,14 @@
+SPHINXOPTS    ?= -jauto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

doc/source/conf.py

@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+
+import sphinx_rtd_theme
+
+# -- Project information -----------------------------------------------------
+
+project = 'python-devicetree'
+
+# Placeholders based on initial provenance of the documentation.
+copyright = u'2021 Zephyr Project members and individual contributors'
+author = 'Zephyr Project'
+
+# The full version, including alpha/beta/rc tags
+release = '0.0.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx_rtd_theme',
+    # Keep this sorted; don't just append new items.
+]
+
+templates_path = ['_templates']
+
+exclude_patterns = []
+
+rst_epilog = f'''
+.. |release| replace:: {release}
+'''
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+
+html_static_path = []

doc/source/dtlib.rst

@@ -0,0 +1,14 @@
+.. _dtlib:
+
+dtlib
+=====
+
+This is the low-level DTS parser.
+
+.. automodule:: devicetree.dtlib
+.. autoclass:: devicetree.dtlib.DT
+   :members:
+   :special-members: __init__
+.. autoclass:: devicetree.dtlib.Node
+.. autoclass:: devicetree.dtlib.Property
+.. autoclass:: devicetree.dtlib.DTError

doc/source/edtlib.rst

@@ -0,0 +1,22 @@
+.. _edtlib:
+
+edtlib
+======
+
+This is the higher level representation that incorporates standard conventions
+for well known properties as well as extra information in Zephyr's bindings
+syntax.
+
+.. automodule:: devicetree.edtlib
+
+.. autoclass:: devicetree.edtlib.EDT
+   :special-members: __init__
+.. autoclass:: devicetree.edtlib.Binding
+   :special-members: __init__
+.. autoclass:: devicetree.edtlib.PropertySpec
+.. autoclass:: devicetree.edtlib.Node
+.. autoclass:: devicetree.edtlib.Property
+.. autoclass:: devicetree.edtlib.Register
+.. autoclass:: devicetree.edtlib.ControllerAndData
+.. autoclass:: devicetree.edtlib.PinCtrl
+.. autoclass:: devicetree.edtlib.EDTError

doc/source/index.rst

@@ -0,0 +1,37 @@
+python-devicetree
+=================
+
+This is part of an ongoing effort to extract the Zephyr Project's
+`devicetree tools`_ to a standalone location for wider use.
+
+This is version |release|. It is based on the Zephyr tools as of commit
+`f5409dec01`_.
+
+.. _devicetree tools:
+   https://docs.zephyrproject.org/latest/guides/dts/intro.html#scripts-and-tools
+
+.. _f5409dec01:
+   https://github.com/zephyrproject-rtos/zephyr/commit/f5409dec01c84aa8eda1830c64309abe3d5868d0
+
+Quickstart
+==========
+
+.. code-block:: sh
+
+   $ pip3 install devicetree
+   $ python3
+   [...]
+   >>> from devicetree import edtlib, dtlib
+
+Then you should be able to use :ref:`edtlib` and :ref:`dtlib` in the same way
+Zephyr does with its in-tree versions of these modules.
+
+This is meant as a way to get started. Breaking API changes to make this code
+easier to use standalone are possible.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   dtlib
+   edtlib