Add readthedocs templates and build rules

Co-authored-by: Timo Korhonen <timo.korhonen@ess.eu>
Co-authored-by: Andrew Johnson <anj@anl.gov>

.readthedocs.yaml

@@ -0,0 +1,36 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+      python: "3.9"
+  apt_packages:
+    - graphviz
+    - rsync
+  jobs:
+    pre_build:
+      - make inc
+      - make -C documentation rtd
+
+# Build documentation in the documentation/ directory with Sphinx
+sphinx:
+  configuration: documentation/conf.py
+
+# Build documentation with MkDocs
+#mkdocs:
+#  configuration: mkdocs.yml
+
+# Optionally build your docs in additional formats such as PDF and ePub
+#formats: []
+
+submodules:
+    exclude: all
+
+python:
+   install:
+      - requirements: documentation/requirements.txt

documentation/.gitignore

@@ -1,3 +0,0 @@
-*.db
-epics-base.tag
-html/

documentation/Doxyfile@

@@ -1841,7 +1841,7 @@ GENERATE_XML           = YES
 # The default directory is: xml.
 # This tag requires that the tag GENERATE_XML is set to YES.
 
-XML_OUTPUT             = rtd-src/xml
+XML_OUTPUT             = @RTD_SRC@/xml
 
 # If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program
 # listings (including syntax highlighting and cross-referencing information) to

documentation/HEADER_h.rst

@@ -0,0 +1,4 @@
+@HEADER@.h
+=======================================
+
+.. doxygenfile:: @HEADER@.h

documentation/Makefile

@@ -7,18 +7,165 @@ EXPAND_ME += EPICS_REVISION
 EXPAND_ME += EPICS_MODIFICATION
 EXPAND_ME += EPICS_PATCH_LEVEL
 EXPAND_ME += OS_CLASS CMPLR_CLASS
+EXPAND_ME += RTD_SRC
 
-TARGETS += doxygen
+DOXYGEN ?= doxygen
 
-DOXYGEN = doxygen
+libcom_HEADERS += adjustment
+libcom_HEADERS += alarm
+libcom_HEADERS += alarmString
+libcom_HEADERS += asTrapWrite
+libcom_HEADERS += bucketLib
+libcom_HEADERS += cantProceed
+libcom_HEADERS += compilerDependencies
+libcom_HEADERS += cvtFast
+libcom_HEADERS += dbmf
+libcom_HEADERS += devLibVME
+libcom_HEADERS += devLibVMEImpl
+libcom_HEADERS += ellLib
+libcom_HEADERS += envDefs
+libcom_HEADERS += epicsAlgorithm
+libcom_HEADERS += epicsAssert
+libcom_HEADERS += epicsAtomic
+libcom_HEADERS += epicsEvent
+libcom_HEADERS += epicsExit
+libcom_HEADERS += epicsExport
+libcom_HEADERS += epicsGeneralTime
+libcom_HEADERS += epicsGuard
+libcom_HEADERS += epicsMessageQueue
+libcom_HEADERS += epicsMutex
+libcom_HEADERS += epicsReadline
+libcom_HEADERS += epicsRingBytes
+libcom_HEADERS += epicsRingPointer
+libcom_HEADERS += epicsSignal
+libcom_HEADERS += epicsSpin
+libcom_HEADERS += epicsStackTrace
+libcom_HEADERS += epicsStdio
+libcom_HEADERS += epicsStdlib
+libcom_HEADERS += epicsString
+libcom_HEADERS += epicsTempFile
+libcom_HEADERS += epicsThread
+libcom_HEADERS += epicsTime
+libcom_HEADERS += epicsTypes
+libcom_HEADERS += epicsUnitTest
+libcom_HEADERS += errlog
+libcom_HEADERS += freeList
+libcom_HEADERS += iocsh
+libcom_HEADERS += ipAddrToAsciiAsynchronous
+libcom_HEADERS += logClient
+libcom_HEADERS += macLib
+libcom_HEADERS += osiPoolStatus
+libcom_HEADERS += osiProcess
+libcom_HEADERS += osiSock
+libcom_HEADERS += postfix
+libcom_HEADERS += shareLib
+libcom_HEADERS += testMain
+libcom_HEADERS += yajl_alloc
+libcom_HEADERS += yajl_common
+libcom_HEADERS += yajl_gen
+libcom_HEADERS += yajl_parse
+
+database_HEADERS += chfPlugin
+database_HEADERS += dbChannel
+database_HEADERS += dbCommon
+database_HEADERS += dbDefs
+database_HEADERS += dbExtractArray
+database_HEADERS += dbLink
+database_HEADERS += dbServer
+database_HEADERS += dbState
+database_HEADERS += dbStaticLib
+database_HEADERS += dbUnitTest
+database_HEADERS += devLib
+database_HEADERS += devSup
+database_HEADERS += drvSup
+database_HEADERS += initHooks
+
+record_HEADERS += aaiRecord
+record_HEADERS += aaoRecord
+record_HEADERS += aiRecord
+record_HEADERS += aoRecord
+record_HEADERS += aSubRecord
+record_HEADERS += biRecord
+record_HEADERS += boRecord
+record_HEADERS += calcRecord
+record_HEADERS += calcoutRecord
+record_HEADERS += compressRecord
+record_HEADERS += dfanoutRecord
+record_HEADERS += eventRecord
+record_HEADERS += fanoutRecord
+record_HEADERS += histogramRecord
+record_HEADERS += int64inRecord
+record_HEADERS += int64outRecord
+record_HEADERS += longinRecord
+record_HEADERS += longoutRecord
+record_HEADERS += lsiRecord
+record_HEADERS += lsoRecord
+record_HEADERS += mbbiRecord
+record_HEADERS += mbbiDirectRecord
+record_HEADERS += mbboRecord
+record_HEADERS += mbboDirectRecord
+record_HEADERS += permissiveRecord
+record_HEADERS += printfRecord
+record_HEADERS += selRecord
+record_HEADERS += seqRecord
+record_HEADERS += stateRecord
+record_HEADERS += stringinRecord
+record_HEADERS += stringoutRecord
+record_HEADERS += subRecord
+record_HEADERS += subArrayRecord
+record_HEADERS += waveformRecord
+
+menu_HEADERS += menuAlarmSevr
+menu_HEADERS += menuAlarmStat
+menu_HEADERS += menuConvert
+menu_HEADERS += menuFtype
+menu_HEADERS += menuIvoa
+menu_HEADERS += menuOmsl
+menu_HEADERS += menuPini
+menu_HEADERS += menuPost
+menu_HEADERS += menuPriority
+menu_HEADERS += menuScan
+menu_HEADERS += menuSimm
+menu_HEADERS += menuYesNo
+
+HEADER_TYPES = libcom database record menu
+
+HEADER_RST_FILES = $(foreach t, $(HEADER_TYPES), \
+    $(addsuffix _h.rst, $($t_HEADERS)))
+API_RST_FILES = $(addsuffix -api.rst, $(HEADER_TYPES))
+
+RTD_SRC = rtd-src
+
+DOCS += README.md
+DOCS += RELEASE_NOTES.md
 
 include $(TOP)/configure/RULES
 
+$(HEADER_RST_FILES): %_h.rst: ../HEADER_h.rst
+	$(EXPAND_TOOL) -t $(INSTALL_LOCATION) -DHEADER=$* $< $@
+
+$(API_RST_FILES): %-api.rst: ../%-API.rst
+	@$(RM) $@
+	@$(ECHO) Creating $@
+	@$(CP) $< $@
+	@$(foreach h, $($*_HEADERS), \
+	    echo "   $h_h.rst" >> $@;)
+
 ifndef T_A
-doxygen: all
+doxygen rtd: inc
+	$(MAKE) -C O.$(EPICS_HOST_ARCH) $@
 else
+
 doxygen: Doxyfile
+	@$(MKDIR) $(RTD_SRC)
 	$(DOXYGEN)
+
+rtd: doxygen $(API_RST_FILES) $(HEADER_RST_FILES)
+	rsync -av $(INSTALL_DOC)/ $(RTD_SRC)/
+	rsync -av $(HEADER_RST_FILES) $(RTD_SRC)/
+	rsync -av $(API_RST_FILES) $(RTD_SRC)/
+	rsync -av ../index.rst ../conf.py $(RTD_SRC)/
+	$(PYTHON) -m sphinx rtd-src _readthedocs/html
 endif
 
-.PHONY: doxygen
+.PHONY: doxygen rtd

documentation/conf.py

@@ -0,0 +1,130 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- 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 = "EPICS base documentation"
+copyright = "EPICS Controls"
+author = "EPICS"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+
+extensions = [
+    "hoverxref.extension",
+    "breathe",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.graphviz",
+    "sphinx_copybutton",
+    "sphinx.ext.intersphinx",
+    'myst_parser',
+]
+
+# Setup the breathe extension
+breathe_projects = {"epics-base": "xml"}
+
+breathe_default_project = "epics-base"
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = "cpp"
+
+# Tell sphinx what the pygments highlight language should be.
+highlight_language = "cpp"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["../modules/libcom/src/cxxTemplates"]
+
+# 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", "O.*", "venv"]
+
+# Intersphinx links to subprojects
+intersphinx_mapping = {
+    "epics": ("https://docs.epics-controls.org/en/latest/", None),
+}
+intersphinx_disabled_reftypes = ["*"]
+hoverxref_role_types = {
+    "hoverxref": "tooltip",
+    "ref": "modal",
+    "confval": "tooltip",
+    "mod": "modal",
+    "class": "modal",
+    "obj": "tooltip",
+}
+
+hoverxref_intersphinx_types = {
+    "readthedocs": "modal",
+    "sphinx": "tooltip",
+}
+
+hoverxref_domains = [
+    "py",
+]
+
+# Enabled Markdown extensions.
+# See here for what they do:
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_image",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "tasklist",
+]
+
+# Allows auto-generated header anchors:
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#auto-generated-header-anchors
+myst_heading_anchors = 4
+
+
+# -- 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"
+
+
+# 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']
+
+# html_css_files = [
+#    'css/custom.css',
+# ]
+
+master_doc = "index"
+
+# html_theme_options = {
+#    'logo_only': True,
+# }
+# html_logo = "images/EPICS_white_logo_v02.png"
+
+# html_extra_path = ['../html']
+
+# Breathe directives

documentation/database-API.rst

@@ -0,0 +1,7 @@
+IOC Database C/C++ APIs
+=======================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: IOC Header Files
+

documentation/index.rst

@@ -0,0 +1,29 @@
+EPICS Document Collection
+=========================
+
+
+.. toctree::
+   :hidden:
+
+   Back <https://docs.epics-controls.org/en/latest/>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: General Information
+
+   RELEASE_NOTES
+
+.. toctree::
+   :maxdepth: 2
+   :caption: IOC Component Reference
+
+   ComponentReference
+
+.. toctree::
+   :maxdepth: 1
+   :caption: C/C++ Headers
+
+   libcom-api
+   database-api
+   record-api
+   menu-api

documentation/libcom-API.rst

@@ -0,0 +1,7 @@
+Common Library C/C++ APIs
+=========================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: LibCom Header Files
+

documentation/menu-API.rst

@@ -0,0 +1,7 @@
+C/C++ Headers from Menus
+=======================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Generated Menu Header Files
+

documentation/record-API.rst

@@ -0,0 +1,7 @@
+C/C++ Headers from Record Types
+===============================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Generated Record Header Files
+

documentation/requirements.txt

@@ -0,0 +1,6 @@
+sphinx==7.2.6
+myst-parser==2.0.0
+breathe==4.35.0
+sphinx_copybutton==0.5.2
+sphinx-hoverxref==1.3.0
+sphinx-rtd-theme==2.0.0