docs/conf.py

# -*- coding: utf-8 -*-
# Copyright (C) 2017-2022 The Project X-Ray Authors.
#
# Use of this source code is governed by a ISC-style
# license that can be found in the LICENSE file or at
# https://opensource.org/licenses/ISC
#
# SPDX-License-Identifier: ISC
#
# Project X-Ray documentation build configuration file, created by
# sphinx-quickstart on Mon Feb  5 11:04:37 2018.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# Updated documentation of the configuration options is available at
# https://www.sphinx-doc.org/en/master/usage/configuration.html

from pathlib import Path
import re
import recommonmark
import os
from sys import path as sys_path
import subprocess

sys_path.insert(0, os.path.abspath('.'))
from markdown_code_symlinks import LinkParser, MarkdownSymlinksDomain

# -- General configuration ------------------------------------------------

project = 'Project X-Ray'
author = 'F4PGA Authors'
copyright = f'{author}, 2018 - 2022'

# yapf: disable
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.doctest',
    'sphinx.ext.imgmath',
    'sphinx.ext.napoleon',
    'sphinx.ext.todo',
    'sphinx_markdown_tables',
    'recommonmark'
]
# yapf: enable

emplates_path = ['_templates']

source_suffix = ['.rst', '.md']
source_parsers = {
    '.md': 'markdown_code_symlinks.LinkParser',
}

master_doc = 'index'

# Enable github links when not on readthedocs
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
if not on_rtd:
    html_context = {
        "display_github": True,  # Integrate GitHub
        "github_user": "f4pga",  # Username
        "github_repo": "prjxray",  # Repo name
        "github_version": "master",  # Version
        "conf_py_path": "/doc/",
    }
else:
    docs_dir = os.path.abspath(os.path.dirname(__file__))
    print("Docs dir is:", docs_dir)
    subprocess.call('git fetch origin --unshallow', cwd=docs_dir, shell=True)
    subprocess.check_call('git fetch origin --tags', cwd=docs_dir, shell=True)
    subprocess.check_call('make links', cwd=docs_dir, shell=True)

# The full version, including alpha/beta/rc tags.
release = re.sub('^v', '', os.popen('git describe ').read().strip())
# The short X.Y version.
version = release

# yapf: disable
exclude_patterns = [
    '_build',
    'architecture/copying.md',
    'db_dev_process/minitests/index/**',
    'db_dev_process/fuzzers/index/**'
]
# yapf: enable

# 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

# -- Options for HTML output ----------------------------------------------

html_show_sourcelink = True

html_theme = 'sphinx_symbiflow_theme'

html_theme_options = {
    'repo_name': 'f4pga/prjxray',
    'github_url' : 'https://github.com/f4pga/prjxray',
    'globaltoc_collapse': True,
    'color_primary': 'indigo',
    'color_accent': 'blue',
}

html_static_path = ['_static']

html_logo = str(Path(html_static_path[0]) / 'logo.svg')
html_favicon = str(Path(html_static_path[0]) / 'favicon.svg')

# -- Options for HTMLHelp output ------------------------------------------

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

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {}

latex_documents = [
    (
        master_doc, 'ProjectX-Ray.tex', u'Project X-Ray Documentation',
        u'F4PGA Authors', 'manual'),
]

# -- Options for manual page output ---------------------------------------

man_pages = [
    (master_doc, 'projectx-ray', u'Project X-Ray Documentation', [author], 1)
]

# -- Options for Texinfo output -------------------------------------------

texinfo_documents = [
    (
        master_doc, 'ProjectX-Ray', u'Project X-Ray Documentation', author,
        'ProjectX-Ray', 'One line description of project.', 'Miscellaneous'),
]

intersphinx_mapping = {'https://docs.python.org/': None}


def setup(app):
    # Generate links for markdown-code-symlinks
    subprocess.check_call("make links", shell=True)

    github_code_repo = 'https://github.com/f4pga/prjxray/'
    github_code_branch = 'blob/master/'

    docs_root_dir = os.path.realpath(os.path.dirname(__file__))
    code_root_dir = os.path.realpath(os.path.join(docs_root_dir, ".."))

    MarkdownSymlinksDomain.init_domain(
        github_code_repo, github_code_branch, docs_root_dir, code_root_dir)
    MarkdownSymlinksDomain.find_links()
    app.add_domain(MarkdownSymlinksDomain)
    app.add_config_value(
        'recommonmark_config', {
            'github_code_repo': github_code_repo,
        }, True)