doc: setup sphinx infrastructure for doc build

This only sets up the infrastructure for building documentation using
Sphinx, along with a few documents to check things out.  We'll continue
with documentation sections in further PRs.

The publishing to our opea-project.github.io site will also come later
as we have that content ready to publish.

Signed-off-by: David B. Kinder <[email protected]>

.gitignore

@@ -0,0 +1 @@
+_build

.known-issues/README

@@ -0,0 +1,55 @@
+This directory contains configuration files to ignore errors found in
+the build and test process which are known to the developers and for
+now can be safely ignored.
+
+To use:
+
+ $ cd <build directory>
+ $ make SOMETHING >& result
+ $ scripts/filter-known-issues.py result
+
+It is included in the source tree so if anyone has to submit anything
+that triggers some kind of error that is a false positive, it can
+include the "ignore me" file, properly documented.
+
+Each file can contain one or more multiline Python regular expressions
+(https://docs.python.org/2/library/re.html#regular-expression-syntax)
+that match an error message. Multiple regular expressions are
+separated by comment blocks (that start with #). Note that an empty
+line still is considered part of the multiline regular expression.
+
+For example
+
+---beginning---
+#
+# This testcase always fails, pending fix ZEP-1234
+#
+.*/tests/kernel/grumpy .* FAIL
+#
+# Documentation issue, masks:
+#
+# /home/e/inaky/z/kernel.git/doc/api/io_interfaces.rst:28: WARNING: Invalid definition: Expected identifier in nested name. [error at 19]
+#  struct dev_config::@65  dev_config::bits
+#  -------------------^
+#
+^(?P<filename>.+/doc/api/io_interfaces.rst):(?P<lineno>[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+]
+^\s+struct dev_config::@[0-9]+  dev_config::bits.*
+^\s+-+\^
+---end---
+
+Note you want to:
+
+- use relateive paths; instead of
+  /home/me/mydir/zephyr/something/somewhere.c you will want
+  ^.*/something/somewhere.c (as they will depend on where it is being
+  built)
+
+- Replace line numbers with [0-9]+, as they will change
+
+- (?P<filename>[-._/\w]+/something/somewhere.c) saves the match on
+  that file path in a "variable" called 'filename' that later you can
+  match with (?P=filename) if you want to match multiple lines of the
+  same error message.
+
+Can get really twisted and interesting in terms of regexps; they are
+powerful, so start small :)

.known-issues/sphinx.conf

@@ -0,0 +1,20 @@
+# Known Sphinx generation messages to ignore
+#
+#
+# for toctree glob, we give patterns that go down many levels that might not
+# contain any documents along the way
+^.*WARNING: toctree glob pattern '.*\/\*' didn't match any documents$
+#
+^.*from sphinx.util import.*$
+# ignore warnings about deprecating features in future Sphinx versions
+^.*RemovedInSphinx80Warning.*$
+#
+^WARNING: while setting up extension myst_parser: Failed to convert typing.Any to a set or tuple$
+#
+^.*WARNING: toctree contains reference to document .*that doesn't have a title: no link will be generated$
+# ignore intradoc targets
+#^.*WARNING: 'myst' cross-reference target not found: '[-a-zA-Z0-9]*' \[myst.xref_missing\]$
+# let's ignore all missing targets for now
+^.*WARNING: 'myst' cross-reference target not found: '[^\']*' \[myst.xref_missing\]$
+# need to ignore .md files not is a toc tree for now too
+^.*md: WARNING: document isn't included in any toctree$

404.rst

@@ -0,0 +1,24 @@
+:orphan:
+
+.. _page-not-found:
+
+Page Not Found
+##############
+
+.. rst-class:: rst-columns2
+
+   .. image:: images/BrokenBlocks.png
+      :align: left
+      :width: 320px
+
+   Sorry. The page you requested was not found on this site.
+
+   Check the address for misspellings.
+   It's also possible we've removed or renamed the page you're looking for.
+
+   Try using the navigation links on the left of this page to navigate
+   the major sections of our site, or use the document search box.
+
+.. raw:: html
+
+   <div style='clear:both'></div>

Makefile

@@ -0,0 +1,102 @@
+# makefile for Sphinx documentation
+#
+
+ifeq ($(VERBOSE),1)
+  Q =
+else
+  Q = @
+endif
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?= -q
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = "OPEA Project"
+BUILDDIR      ?= _build
+SOURCEDIR     = $(BUILDDIR)/rst
+LATEXMKOPTS   = "-silent -f"
+
+# Document publication assumes the folder structure is setup with the
+# opea-project repos: GenAIExamples (etc), docs, and opea.github.io repos as
+# sibling folders. make is run inside the opea-project/docs folder. Content from
+# other sibling repos is copied to a build folder to get all content in one
+# tree.
+
+
+OPEA_BASE     = $(CURDIR)/..
+DOC_TAG      ?= development
+RELEASE      ?= latest
+PUBLISHDIR    = $(OPEA_BASE)/opea-project.github.io/$(RELEASE)
+RSYNC_OPTS    = -am --exclude='.github/*' --include='*/' --include-from=scripts/rsync-include.txt --exclude='*'
+RSYNC_DIRS    = GenAIComps  GenAIEval  GenAIExamples  GenAIInfra  Governance
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(OPTS)
+	@echo ""
+	@echo "make publish"
+	@echo "   publish generated html to opea.github.io site:"
+	@echo "   specify RELEASE=name to publish as a tagged release version"
+	@echo "   and placed in a version subfolder.  Requires repo merge permission."
+
+.PHONY: help Makefile content html singlehtml clean publish
+
+# Copy all the rst and md content (and images, etc) into the _build/rst folder
+# including rst and md content
+
+# GenAIComps  GenAIEval  GenAIExamples  GenAIInfra  Governance
+content:
+	$(Q)mkdir -p $(SOURCEDIR)
+	$(Q)rsync -a --exclude=$(BUILDDIR) . $(SOURCEDIR)
+#	$(Q)for dir in $(RSYNC_DIRS); do\
+#		rsync $(RSYNC_OPTS) ../$$dir $(SOURCEDIR); \
+#		done
+# temporarily, copy docs content too (were in the docs-work)
+#	$(Q)rsync $(RSYNC_OPTS) ../docs/* $(SOURCEDIR)
+#	$(Q)find $(SOURCEDIR) -type f -empty -name "README.md" -delete
+#	$(Q)scripts/fix-github-md-refs.sh $(SOURCEDIR)
+
+
+html: content
+	@echo making HTML content
+	$(Q)./scripts/show-versions.py
+	-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b html -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(OPTS) >> $(BUILDDIR)/doc.log 2>&1
+	$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
+
+singlehtml: content 
+	-$(Q)$(SPHINXBUILD) -t $(DOC_TAG) -b singlehtml -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(OPTS) >> $(BUILDDIR)/doc.log 2>&1
+	$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
+
+pdf: html
+	@echo now making $(BUILDDIR)/latex/opea.pdf
+	$(Q)make -silent latexpdf LATEXMKOPTS=$(LATEXMKOPTS) >> $(BUILDDIR)/doc.log 2>&1
+	$(Q)./scripts/filter-doc-log.sh $(BUILDDIR)/doc.log
+
+
+# Remove generated content
+
+clean:
+	rm -fr $(BUILDDIR)
+
+# Copy material over to the GitHub pages staging repo
+# along with a README, index.html redirect to latest/index.html, robots.txt (for
+# search exclusions), and tweak the Sphinx-generated 404.html to work as the
+# site-wide 404 response page.  (We generate the 404.html with Sphinx so it has
+# the current left navigation contents and overall style.)
+
+publish:
+	mkdir -p $(PUBLISHDIR)
+	cd $(PUBLISHDIR)/..; git pull origin main
+	rm -fr $(PUBLISHDIR)/*
+	cp -r $(BUILDDIR)/html/* $(PUBLISHDIR)
+ifeq ($(RELEASE),latest)
+	cp scripts/publish-README.md $(PUBLISHDIR)/../README.md
+	scripts/publish-redirect.sh $(PUBLISHDIR)/../index.html latest/index.html
+	sed 's/<head>/<head>\n  <base href="https:\/\/opea-project.github.io\/latest\/">/' $(BUILDDIR)/html/404.html > $(PUBLISHDIR)/../404.html
+endif
+	cd $(PUBLISHDIR)/..; git add -A; git commit -s -m "publish $(RELEASE)"; git push origin main;
+
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(OPTS) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(OPTS)