Add docs with Sphinx

docs/.github/workflows/sphinx.yml

@@ -0,0 +1,24 @@
+name: "Sphinx: Render docs"
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build HTML
+      uses: ammaraskar/sphinx-action@master
+    - 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     = .
+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/README.md

@@ -0,0 +1,35 @@
+# Open Metadata Exchange (OME)
+OME enables open educational resources to create, publish, and update their metadata
+on a peer-to-peer network.  By solving authoring, publishing, and discovery issues,
+this network will provide broad visibility to current islands of OER information.
+
+## Features
+* Define a metadata model for sharing information about open educational resources.
+* Define a distributed network for sharing this metadata in a non-centralized yet resilient way.
+* Define a node for this network that is easy to install and use.
+* Provide pedigree information for each record in the network.
+* Suggest storage strategies for retaining metadata even if its original author leaves the network.
+
+## Installation
+Install Open Metadata Exchange by running:
+* `apt-get install open-metadata-exchange` (Asperational!)
+
+## Contribute
+* Issue Tracker: https://github.com/ISKME/Open-Metadata-Exchange/issues
+* Source Code: https://github.com/ISKME/Open-Metadata-Exchange
+
+## Support
+Please open an issue in our [Issue Tracker](https://github.com/ISKME/Open-Metadata-Exchange/issues).
+
+## License
+The project is licensed under the __GNU Affero General Public License v3.0__.
+
+---
+
+# Open Metadata Exchange Overview
+
+__Analogy__: Imagine a librarian creates a catalog card for a new book. Once the card is made, the librarian makes copies and sends them to neighboring libraries. Those libraries do the same, spreading the information further. Each library may choose to add specific details relevant to its own collection, but they don't have to start from scratch. Any updates to the cards are also shared. This process ensures efficient sharing and updating of information across libraries.
+
+__Practical Implementation__: OME would create a standardized format for Open Educational Resources (OER), similar to iCal. This would operate on a peer-to-peer network using Docker-based nodes using store-and-forward information replication. APIs will be available for creating, modifying, and deleting entries in the local node. Each node stores information and forwards modifications to neighboring nodes. There will be a user interface to view, import, and export data on the exchange. Nodes will automatically handle the storage and forwarding of the collaboratively created metadata.
+
+__Problem Solved__: OME addresses an "islands of information" issue. Currently, OER creators work in isolation, creating fragmented resources. OME aims to connect these "islands" so that contributors can discover and enhance each other's work.  Resources can be preserved even if the original creator is no longer active. This will simplify the discovery and tagging process, ensuring that the effort spent on these tasks benefits the entire network and is not unnecessarily duplicated across different digital libraries.

docs/conf.py

@@ -0,0 +1,32 @@
+# 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 = "Open Metadata Exchange"
+version = "0.0.1"
+copyright = "2024, ISKME and contributors"
+author = "ISKME and contributors"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "markdown",
+    ".md": "markdown",
+}
+suppress_warnings = ["epub.unknown_project_files"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["_static"]

docs/index.md

@@ -0,0 +1,8 @@
+# Open Metadata Exchange documentation
+```{toctree}
+:maxdepth: 2
+:caption: # Table of Contents
+
+README.md
+```
+ISKME and contributors

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd