conf.py

# -*- coding: utf-8 -*-
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a full list see the
# documentation: https://www.sphinx-doc.org/en/master/usage/configuration.html

import time

project = 'AgileX SCOUT MINI Documentation'
author = 'Trossen Robotics'
copyright = "{}, {}".format(time.strftime("%Y"), author)

# The short X.Y version
version = ''
# The full version, including alpha/beta/rc tags
release = ''

# Add any Sphinx extension module names here, as strings. They can be extensions coming with Sphinx
# (named 'sphinx.ext.*') or your custom ones.
extensions = [
    'sphinx.ext.imgmath',
    'sphinx.ext.githubpages',
    'sphinx.ext.extlinks',
    'sphinx.ext.graphviz',
    'sphinxcontrib.youtube',
    'sphinx_copybutton',
    'sphinx_tabs.tabs',
]

# Used by the sphinx_copybutton extension - Define the prompt text that should be removed from
# copied text in code blocks.
copybutton_prompt_text = '$ '

# Add any paths that contain templates here, relative to this directory.
templates_path = [
    '_templates'
]

# The suffix(es) of source filenames. You can specify multiple suffix as a list of string:
source_suffix = '.rst'

# The master toctree document.
master_doc = 'index'

# 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 pattern also affects html_static_path and html_extra_path .
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# -- 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'

# If true, images itself links to the original image if it doesn’t have
# ‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’.
html_scaled_image_link = False

# Set the html page title
html_title = "AgileX SCOUT MINI Documentation"

# Activate the bootstrap theme.
# html_theme_path = ['_themes']
# html_theme = 'bootstrap'

# 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 = {
    # If enabled, navigation entries are not expandable
    'collapse_navigation': True,
    # Scroll the navigation with the main page content as you scroll the page.
    'sticky_navigation': True,
    # The maximum depth of the table of contents tree. Set this to -1 to allow unlimited depth.
    'navigation_depth': -1,
    # Specifies if the navigation includes hidden table(s) of contents – that is, any toctree
    # directive that is marked with the :hidden: option.
    'includehidden': True,
    # When enabled, page subheadings are not included in the navigation.
    'titles_only': False,
    # If True, the version number is shown at the top of the sidebar.
    'display_version': False,
    # Only display the logo image, do not display the project name at the top of the sidebar
    'logo_only': True,
    # Add an icon next to external links.
    'style_external_links': False,
}

# The name of an image file (relative to this directory) to place at the top of the sidebar.
html_logo = "_images/logo_scout_mini.png"

# 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',
]

# These paths are either relative to html_static_path or fully qualified paths (eg. https://...)
html_css_files = [
    'tr_style.css',
]

# The name of an image file (relative to this directory) to use as a favicon of the docs.  This
# file should be a Windows icon file (.ico) being 16x16 or 32x32 pixels large.
html_favicon = 'favicon.ico'

# Suffix to be appended to source links, unless they have this suffix already.
html_sourcelink_suffix = ''

html_context = {
    'display_github': True, # Integrate GitHub
    'github_user': 'TrossenRobotics', # Username
    'github_repo': 'agilex_scout_mini_docs', # Repo name
    'github_version': 'main/', # Version
    'conf_py_path': '', # Path in the checkout to the docs root
    'source_suffix': '.rst', # Change source suffix to rst
}

# Output file base name for HTML help builder.
htmlhelp_basename = 'AgileXScoutMINIDocumentation'

# make external links open in new tab
#   https://stackoverflow.com/a/61669375

from sphinx.writers.html import HTMLTranslator
from docutils import nodes
from docutils.nodes import Element

class PatchedHTMLTranslator(HTMLTranslator):

    def visit_reference(self, node: Element) -> None:
        atts = {'class': 'reference'}
        if node.get('internal') or 'refuri' not in node:
            atts['class'] += ' internal'
        else:
            atts['class'] += ' external'
            # ---------------------------------------------------------
            # Customize behavior (open in new tab, secure linking site)
            atts['target'] = '_blank'
            atts['rel'] = 'noopener noreferrer'
            # ---------------------------------------------------------
        if 'refuri' in node:
            atts['href'] = node['refuri'] or '#'
            if self.settings.cloak_email_addresses and atts['href'].startswith('mailto:'):
                atts['href'] = self.cloak_mailto(atts['href'])
                self.in_mailto = True
        else:
            assert 'refid' in node, \
                   'References must have "refuri" or "refid" attribute.'
            atts['href'] = '#' + node['refid']
        if not isinstance(node.parent, nodes.TextElement):
            assert len(node) == 1 and isinstance(node[0], nodes.image)
            atts['class'] += ' image-reference'
        if 'reftitle' in node:
            atts['title'] = node['reftitle']
        if 'target' in node:
            atts['target'] = node['target']
        self.body.append(self.starttag(node, 'a', '', **atts))

        if node.get('secnumber'):
            self.body.append(('%s' + self.secnumber_suffix) %
                             '.'.join(map(str, node['secnumber'])))

def setup(app):
    app.set_translator('html', PatchedHTMLTranslator)