Add readthedocs templates and build rules
Co-authored-by: Timo Korhonen <timo.korhonen@ess.eu> Co-authored-by: Andrew Johnson <anj@anl.gov>
This commit is contained in:
Minijackson
committed by
Andrew Johnson
Andrew Johnson
parent
ad7575f5a4
commit
8c88d052bb
36
.readthedocs.yaml
Normal file
36
.readthedocs.yaml
Normal file
@ -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
|
||||
3
documentation/.gitignore
vendored
3
documentation/.gitignore
vendored
@ -1,3 +0,0 @@
|
||||
*.db
|
||||
epics-base.tag
|
||||
html/
|
||||
@ -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
|
||||
|
||||
4
documentation/HEADER_h.rst
Normal file
4
documentation/HEADER_h.rst
Normal file
@ -0,0 +1,4 @@
|
||||
@HEADER@.h
|
||||
=======================================
|
||||
|
||||
.. doxygenfile:: @HEADER@.h
|
||||
@ -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
|
||||
|
||||
130
documentation/conf.py
Normal file
130
documentation/conf.py
Normal file
@ -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
|
||||
7
documentation/database-API.rst
Normal file
7
documentation/database-API.rst
Normal file
@ -0,0 +1,7 @@
|
||||
IOC Database C/C++ APIs
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: IOC Header Files
|
||||
|
||||
29
documentation/index.rst
Normal file
29
documentation/index.rst
Normal file
@ -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
|
||||
7
documentation/libcom-API.rst
Normal file
7
documentation/libcom-API.rst
Normal file
@ -0,0 +1,7 @@
|
||||
Common Library C/C++ APIs
|
||||
=========================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: LibCom Header Files
|
||||
|
||||
7
documentation/menu-API.rst
Normal file
7
documentation/menu-API.rst
Normal file
@ -0,0 +1,7 @@
|
||||
C/C++ Headers from Menus
|
||||
=======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Generated Menu Header Files
|
||||
|
||||
7
documentation/record-API.rst
Normal file
7
documentation/record-API.rst
Normal file
@ -0,0 +1,7 @@
|
||||
C/C++ Headers from Record Types
|
||||
===============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Generated Record Header Files
|
||||
|
||||
6
documentation/requirements.txt
Normal file
6
documentation/requirements.txt
Normal file
@ -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
|
||||
Reference in New Issue
Block a user