conf.py

Go to the documentation of this file.

import subprocess
from typing import List
 
from docutils.parsers.rst.directives.admonitions import BaseAdmonition
from docutils import nodes
from sphinx.util.docutils import SphinxDirective
from sphinx import addnodes
 
import sphinx_eso_theme
# Notes
# -----
#
# Raster images are assumed to be exported from Magicdraw in 288dpi png.
# To get a 1:1 size compared with what you see in Magicdraw the image must be scaled
# to 33%
 
extensions = ['sphinx.ext.intersphinx',
    'sphinx.ext.ifconfig',
    'sphinx.ext.graphviz',
    'sphinx.ext.mathjax',
    'sphinxcontrib.plantuml',
    'sphinx_eso_theme']
 
source_suffix = '.rst'
 
# The master toctree document.
master_doc = 'index'
 
# Use numbered figures
numfig = True
# General information about the project.
project = 'IFW Data Acquisition User Manual'
# note the leading space which is required to avoid SOURCE_DATE_EPOCH being used.
copyright = ' 2022 ESO - European Southern Observatory'
homepage = r'https://gitlab.eso.org/ifw/ifw-daq'
 
 
#############################################################################
 
rst_prolog = """
.. |configpath| replace:: :term:`Config Path`
.. |recif| replace:: :term:`recif`
.. |dpspec| replace:: :term:`Data Product Specification`
 
.. |daq| replace:: :term:`Data Acquisition`
.. |daqs| replace:: :term:`Data Acquisitions <Data Acquisition>`
.. |dp| replace:: *Data Product*
.. |dps| replace:: *Data Products*
.. |ocm| replace:: :ref:`OCM<ocm>`
.. |dpm| replace:: :ref:`DPM<dpm>`
.. |cii| replace:: :ref:`CII<def-cii>`
.. |olas| replace:: :ref:`OLAS<def-olas>`
.. |oldb| replace:: :ref:`OLDB<def-oldb>`
.. |named-json| replace:: :sup:`{JSON}`
.. |rad| replace:: :ref:`RAD<def-rad>`
 
.. |ocmserver| replace:: :ref:`daqOcmServer <daqOcmServer>`
.. |ocmctl| replace:: :ref:`daqOcmCtl <daqOcmCtl>`
.. |dpmserver| replace:: :ref:`daqDpmServer <daqDpmServer>`
.. |dpmmerge| replace:: :ref:`daqDpmMerge <daqDpmMerge>`
.. |dpmworkspace| replace:: :ref:`daqDpmServer workspace <dpmWorkspace>`
.. |rd1| replace:: :ref:`RD1 <rd1>`
.. |rd2| replace:: :ref:`RD2 <rd2>`
.. |rd3| replace:: :ref:`RD3 <rd3>`
.. |rd4| replace:: :ref:`RD4 <rd4>`
.. |rd-fits| replace:: :ref:`RD5 <rd5>`
.. |rd-cfitsio| replace:: :ref:`RD8 <rd8>`
.. |rd-esokw| replace:: :ref:`RD6 <rd6>`
.. |rd-olasicd| replace:: :ref:`RD7 <rd7>`
.. |rd-rad| replace:: :ref:`RD9 <rd9>`
"""
 
#############################################################################
# Update for each release:
author='Rosenquist, Calle'
latex_attrs = dict(
        pdm_version='n',
        release_date='2021-xx-xx',
        owner=author,
        validated_pm='Kornweibel, Nick',
        validated_se='González Herrera, Juan Carlos',
        validated_pe='Biancat Marchet, Fabio',
        approved_pgm='Tamai, Roberto')
 
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '3.0.0-pre2'
prerelease = "-pre" in version
 
# The full version, including alpha/beta/rc tags.
release = version
ifw_release = '4.0'
if prerelease:
    try:
        rev = subprocess.run(["git", "rev-parse", "--short=5", "HEAD"],
                stdout=subprocess.PIPE).stdout.decode("utf-8")
        suffix = "+git.%s" % rev
        release += suffix
        version += suffix
    except Exception:
        pass
#############################################################################
 
 
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = []
 
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'default'
# Disable default Python 3 highlighting in literal blocks `::`
highlight_language = 'none'
 
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
 
plantuml_batch_size = 100
 
# -- 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_eso_theme'
html_theme_path = ['_themes/', ]
html_show_sourcelink = False
html_copy_source = False
 
# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
 
# 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_logo = '_static/eso_logo.png'
#html_favicon = '_static/eso-favicon.ico'
 
# ESO customization of theme colors mostly.
html_context = {}
 
 
html_show_sphinx = False
 
 
# -- Options for LaTeX output ---------------------------------------------
# The ESO PDM style only supports the article class so we map manual to article class
# and set the top level sectioning to use 'section' as otherwise 'chapter' would be used, which is
# ignored for the article class.
latex_toplevel_sectioning = 'section'
latex_docclass = dict(manual='article')
latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    'papersize': 'a4paper',
 
    # The font size ('10pt', '11pt' or '12pt').
    #
    'pointsize': '11pt',
 
    # Additional stuff for the LaTeX preamble.
    #
    'preamble':
        r'''
        \usepackage[public]{eso-pdm}
        \pdmProgram{ELT}
        \pdmProject{Instrumentation Framework}
        \pdmTitle{ELT~ICS~Framework Data Acquisition\\User~Manual}
        \pdmHeaderTitle{ELT~ICS~Framework - Data Acquisition - User~Manual}
        \pdmDocId{ESO-396401}
        \pdmDocVersion{%(pdm_version)s}
        \pdmDocType{User Manual (MAN)}
        \pdmDocDate{%(release_date)s}
        \pdmSignatureList{
            \pdmSignature{Owner}{%(owner)s}
            \pdmSignature{Validated by PM}{%(validated_pm)s}
            \pdmSignature{Validated by SE}{%(validated_se)s}
            \pdmSignature{Validated by PE}{%(validated_pe)s}
            \pdmSignature{Approved by PGM}{%(approved_pgm)s}
        }
        %% Disable pagestyle changes as it breaks ESO PDM style
        \renewcommand{\pagestyle}[1]{}
        ''' % latex_attrs,
    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
    'sphinxsetup': \
        'hmargin={0.7in,0.7in}, vmargin={1in,1in}, \
        verbatimwithframe=true, \
        OuterLinkColor={rgb}{0,0,0.6}, \
        InnerLinkColor={rgb}{0,0,0}, \
        warningBorderColor={rgb}{0.8,0,0}, \
        cautionBorderColor={rgb}{1,0.8,0}, \
        TitleColor={rgb}{0,0,0}',
    'printindex': r'\newpage',
    'maketitle': r'''
    \pdmmaketitle
 
    %% Scope redefinition of clearpage to relax to avoid new pages for each
    \begingroup
    \let\clearpage\relax
 
    \section*{Release}
    This document corresponds to
    \sphinxhref{%(homepage)s}{\texttt{ifw-hl}\footnote{\sphinxnolinkurl{%(homepage)s}}} v%(ifw_release)s.
 
    \section*{Authors}
    \begin{tabularx}{\linewidth}{|p{0.25\linewidth}|X|}
      \hline
      \multicolumn{1}{|l|}{\textbf{Name}}\tbspa &
      \multicolumn{1}{l|}{\textbf{Affiliation}} \tbspb\\
      \hline
      \tbspa %(author)s & ESO/DOE/CSE\tbspb\\ \hline
    \end{tabularx}
 
    \section*{Change Record from previous Version}
    \begin{tabularx}{\linewidth}{|p{0.25\linewidth}|X|}
      \hline
      \multicolumn{1}{|l|}{\textbf{Affected Section(s)}}\tbspa &
      \multicolumn{1}{l|}{\textbf{Changes / Reason / Remarks}} \tbspb\\
      \hline
      \tbspa All & First version \tbspb\\ \hline
    \end{tabularx}
 
    %% Restore \clearpage
    \endgroup
    \tymin=60pt
    \tymax=\maxdimen
    \hyphenation{Status-Topic}
 
    ''' % dict(release=release, ifw_release=ifw_release, author=author, homepage=homepage),
    'tableofcontents': r'\tableofcontents\newpage',
}
 
latex_show_urls = 'footnote'
 
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
   ('index-latex', 'ELT_ICS_Framework_-_Data_Acquisition_-_User_Manual.tex',
    'ELT ICS Framework - Data Acquisition - User Manual',
    author, 'manual', False),
]
 
 
class Internal(SphinxDirective, BaseAdmonition):
 
    required_arguments = 0
    optional_arguments = 1
    final_argument_whitespace = True
    option_spec = {}
    has_content = True
    node_class = nodes.admonition
 
    def run(self) -> List[nodes.Node]:
        self.options['class'] = ['attention']
        if len(self.argumentsarguments) == 0:
            self.argumentsarguments = ["Internal"]
 
        nodes = super().run()
 
        # Wrap nodes as children to ifconfig
        node = addnodes.only()
        self.set_source_info(node)
        node['expr'] = "internal"
        node.document = self.state.document
        node.children = nodes
        return [node]
 
 
def setup(app):
    app.add_config_value('prerelease', False, 'env')
    app.add_directive('internal', Internal)