conf.py

Go to the documentation of this file.

import sphinx_eso_theme
import subprocess
 
# 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'
exclude_patterns = ['src/dpm.rst']
# 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 = ' 2021 ESO - European Southern Observatory'
homepage = r'https://gitlab.eso.org/ifw/ifw-hl'
 
 
#############################################################################
 
rst_prolog = """
.. |daq| replace:: *Data Acquisition*
.. |daqs| replace:: *Data Acquisitions*
.. |dp| replace:: *Data Product*
.. |ocm| replace:: :ref:`OCM<ocm>`
.. |dpm| replace:: *DPM*
.. |olas| replace:: :ref:`OLAS<def-olas>`
.. |configpath| replace:: :term:`Config Path`
.. |recif| replace:: :term:`recif`
.. |ocmserver| replace:: :ref:`ocmServer <ocmServer>`
.. |ocmserverctl| replace:: :ref:`ocmServerCtl <ocmServerCtl>`
"""
 
#############################################################################
# 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 = '1.0.0'
prerelease = False
# The full version, including alpha/beta/rc tags.
release = '1.0.0'
ifw_release = '3.0.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'
 
# 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),
]
 
 
def setup(app):
    app.add_config_value('prerelease', False, 'env')