From 8c88d052bbe041f2c61935bb7a4d8f42692442f9 Mon Sep 17 00:00:00 2001 From: Minijackson Date: Fri, 1 Sep 2023 11:37:08 +0200 Subject: [PATCH] Add readthedocs templates and build rules Co-authored-by: Timo Korhonen Co-authored-by: Andrew Johnson --- .readthedocs.yaml | 36 ++++++++ documentation/.gitignore | 3 - documentation/Doxyfile@ | 2 +- documentation/HEADER_h.rst | 4 + documentation/Makefile | 155 ++++++++++++++++++++++++++++++++- documentation/conf.py | 130 +++++++++++++++++++++++++++ documentation/database-API.rst | 7 ++ documentation/index.rst | 29 ++++++ documentation/libcom-API.rst | 7 ++ documentation/menu-API.rst | 7 ++ documentation/record-API.rst | 7 ++ documentation/requirements.txt | 6 ++ 12 files changed, 385 insertions(+), 8 deletions(-) create mode 100644 .readthedocs.yaml delete mode 100644 documentation/.gitignore create mode 100644 documentation/HEADER_h.rst create mode 100644 documentation/conf.py create mode 100644 documentation/database-API.rst create mode 100644 documentation/index.rst create mode 100644 documentation/libcom-API.rst create mode 100644 documentation/menu-API.rst create mode 100644 documentation/record-API.rst create mode 100644 documentation/requirements.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..048e5c37a --- /dev/null +++ b/.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 diff --git a/documentation/.gitignore b/documentation/.gitignore deleted file mode 100644 index 52230970a..000000000 --- a/documentation/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -*.db -epics-base.tag -html/ diff --git a/documentation/Doxyfile@ b/documentation/Doxyfile@ index 8c14a5146..7462156d1 100644 --- a/documentation/Doxyfile@ +++ b/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 diff --git a/documentation/HEADER_h.rst b/documentation/HEADER_h.rst new file mode 100644 index 000000000..5e15e130a --- /dev/null +++ b/documentation/HEADER_h.rst @@ -0,0 +1,4 @@ +@HEADER@.h +======================================= + +.. doxygenfile:: @HEADER@.h diff --git a/documentation/Makefile b/documentation/Makefile index 2d5c9a4ee..169d7bf05 100644 --- a/documentation/Makefile +++ b/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 diff --git a/documentation/conf.py b/documentation/conf.py new file mode 100644 index 000000000..127e07102 --- /dev/null +++ b/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 diff --git a/documentation/database-API.rst b/documentation/database-API.rst new file mode 100644 index 000000000..a7e230d53 --- /dev/null +++ b/documentation/database-API.rst @@ -0,0 +1,7 @@ +IOC Database C/C++ APIs +======================= + +.. toctree:: + :maxdepth: 1 + :caption: IOC Header Files + diff --git a/documentation/index.rst b/documentation/index.rst new file mode 100644 index 000000000..6775cb0e8 --- /dev/null +++ b/documentation/index.rst @@ -0,0 +1,29 @@ +EPICS Document Collection +========================= + + +.. toctree:: + :hidden: + + Back + +.. 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 diff --git a/documentation/libcom-API.rst b/documentation/libcom-API.rst new file mode 100644 index 000000000..5d1305f41 --- /dev/null +++ b/documentation/libcom-API.rst @@ -0,0 +1,7 @@ +Common Library C/C++ APIs +========================= + +.. toctree:: + :maxdepth: 1 + :caption: LibCom Header Files + diff --git a/documentation/menu-API.rst b/documentation/menu-API.rst new file mode 100644 index 000000000..27577136f --- /dev/null +++ b/documentation/menu-API.rst @@ -0,0 +1,7 @@ +C/C++ Headers from Menus +======================= + +.. toctree:: + :maxdepth: 1 + :caption: Generated Menu Header Files + diff --git a/documentation/record-API.rst b/documentation/record-API.rst new file mode 100644 index 000000000..880fa94aa --- /dev/null +++ b/documentation/record-API.rst @@ -0,0 +1,7 @@ +C/C++ Headers from Record Types +=============================== + +.. toctree:: + :maxdepth: 1 + :caption: Generated Record Header Files + diff --git a/documentation/requirements.txt b/documentation/requirements.txt new file mode 100644 index 000000000..f1d6f0bdb --- /dev/null +++ b/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