Doctest

.github/workflows/sphinx.yml

@@ -0,0 +1,25 @@
+name: "Sphinx: Render docs"
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@dev
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: html-docs
+        path: docs/build/html/
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/main'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+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)

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx-rtd-theme>=3.0.2
+myst-parser>=3.0.1
+myst>=1.0.4
+sphinxcontrib-mermaid>=1.0.0

CHANGES.md → docs/source/CHANGES.md

@@ -1,3 +1,5 @@
+# Changelog
+
 ## Version 0.1.1
 
 * Make it possible to pass options like `file_format` to `to_image`.

docs/source/api.rst

@@ -0,0 +1,45 @@
+API
+==================
+
+Abstract base classes
+---------------------
+
+.. automodule:: abstracttree.tree
+   :members:
+   :show-inheritance:
+
+.. automodule:: abstracttree.binarytree
+   :members:
+   :show-inheritance:
+
+Adapters
+------------------
+
+.. automodule:: abstracttree.adapters
+   :members: astree, convert_tree
+   :show-inheritance:
+
+Export
+------------------
+
+.. automodule:: abstracttree.export
+   :members:
+   :show-inheritance:
+
+Predicates
+------------------
+.. automodule:: abstracttree.predicates
+   :members:
+   :show-inheritance:
+
+HeapTree
+------------------
+.. automodule:: abstracttree.heaptree
+   :members: HeapTree
+   :show-inheritance:
+
+Route
+------------------
+.. automodule:: abstracttree.route
+   :members: Route
+   :show-inheritance:

docs/source/conf.py

@@ -0,0 +1,46 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+
+project = 'AbstractTree'
+copyright = '2024, Laurent Verweijen'
+author = 'Laurent Verweijen'
+release = 'stable'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.viewcode',
+    'myst_parser',
+    'sphinxcontrib.mermaid'
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+
+myst_enable_extensions = ["colon_fence"]
+
+# Code is in src. Make sure sphinx can find it
+import sys
+from pathlib import Path
+src_folder = Path(__file__).parent.parent.parent / "src"
+print(src_folder)
+sys.path.insert(0, str(src_folder.resolve(strict=True)))

docs/source/index.rst

@@ -0,0 +1,29 @@
+.. AbstractTree documentation master file, created by
+   sphinx-quickstart on Mon Feb 19 18:11:55 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to AbstractTree's documentation!
+========================================
+
+Trees are very common data structure that represents a hierarchy of common nodes.
+This package defines abstract base classes for these data structure in order to make code reusable.
+It also provides an ``astree`` adapter in case it's not possible to inherit from any of these classes.
+Finally, it provides many exports that even work on objects that don't inherit from any of the abstract base classes.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage_bundled
+   api
+   CHANGES
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/installation.rst

@@ -0,0 +1,17 @@
+Installation
+========================================
+
+Use `pip <https://pip.pypa.io/en/stable/getting-started/>`_ to install littletree::
+
+    $ pip install --upgrade littletree
+
+In addition you may want to install the following for some export functions::
+
+    $ pip install --upgrade matplotlib
+    $ pip install --upgrade pillow
+
+For some export functions it might help to install:
+
+- `Graphviz <https://graphviz.org/download/>`_
+- `Mermaid <https://github.com/mermaid-js/mermaid-cli>`_
+- `LaTeX <https://www.latex-project.org/get/>`_