conf.py

# 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:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import os
import sys
from datetime import datetime
import yaml

# -- 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.
sys.path.insert(0, os.path.abspath('.'))


# -- Split configurations ----------------------------------------------------

from _conf.schemas import _schemas
from _conf.deploy import D

# For `.. only::` directive.
if D.is_private():
    tags.add('private') # type: ignore

with open('./_conf/redirect.yml') as data:
    _redirects = yaml.safe_load(data)

# -- Project information -----------------------------------------------------

project = '银色子弹'
author = 'Shengyu Zhang'
author_id = 'SilverRainZ'
author_nick = 'LA'
copyright = '2020-%s, ' % datetime.now().year + author

# -- Non-standard project information ----------------------------------------

logo = '_static/logo.png'
description = 'Yes silver bullet here.'
datefmt = '%Y-%m-%d'

# -- Enviroment information -----------------------------------------------------

# -- 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 = [
    'sphinx.ext.graphviz',
    'sphinxcontrib.email',
    'sphinx.ext.githubpages',
    'sphinxnotes.strike',
    'sphinxcontrib.plantuml',
    'sphinxcontrib.asciinema',
    'sphinx_copybutton',
    'sphinxcontrib.youtube',
    'sphinxnotes.extweb',
    'sphinx_design',
    'sphinx_simplepdf', # .. pdf-include::
]

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

# 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 = 'zh_CN'
language_full = '简体中文'

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

# A string of reStructuredText that will be included at the end of every
# source file that is read.
rst_epilog = """
"""

# Provided by sphinxnotes.any
primary_domain = 'any'

# Use :code: as default role, so we can write `content` instead of ``content``.
default_role = 'code'

# Keep warnings as “system message” paragraphs in the built documents.
# Regardless of this setting, warnings are always written to the standard error
# stream when sphinx-build is run.
# See also suppress_
if D.is_private():
    keep_warnings = True

# A list of warning codes to suppress arbitrary warning messages.
if D is D.Local:
    suppress_warnings = ['ref.' + x.objtype for x in _schemas]

# Auto numbered figures, tables and code-blocks if they have a caption.
# numfig = True

# Show codeauthor and sectionauthor directives produce any output in the built
# files.
show_authors = True

# A URL to cross-reference manpage directives.
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'

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

# 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 = ['custom.css']

# A list of JavaScript filename.
# The entry must be a filename string or a tuple containing the filename string
# and the attributes dictionary. The filename must be relative to the
# html_static_path, or a full URI with scheme like https://example.org/script.js.
# The attributes is used for attributes of <script> tag. It defaults to an empty list.
html_js_files = []

html_baseurl = D.url()

html_title = project

html_logo = logo

html_favicon = '_static/favicon.png'

# HTML theme configuration
html_theme = 'sphinx_book_theme'
html_theme_options = {
    'repository_url': f'https://github.com/{author_id}/bullet',
    'use_repository_button': True,
    'use_download_button': False,
    'use_edit_page_button': False,
    'use_source_button': True,
    'use_issues_button': True,
    'show_toc_level': 2,
    'navigation_with_keys': False, # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/configuring.html#changing-pages-with-keyboard-presses
}

# Setup announcement as your need
# html_theme_options['announcement'] = '</p>blahblah… </p>

if D.is_mirror():
    src = D.Github
    msg = f'<p> 这是部署于 {D} 的镜像，访问源站点：<a class="source-page" href="{src.url()}">{src}</a></p>'
    if html_theme_options.get('announcement'):
        html_theme_options['announcement'] += msg
    else:
        html_theme_options['announcement'] = msg
    html_js_files.append('mirror-redirect.js')

html_css_files.append('sphinx-book-theme-custom.css')

nosidebar_page = ['nosidebar']
blog_post_page = [ # Provided by sphinx_book_theme
                  'navbar-logo',
                  # Provided by ABlog
                  'ablog/postcard', 'ablog/recentposts', 'ablog/tagcloud',
                  'ablog/categories', 'ablog/archives']
# TODO...

html_sidebars = {
    # We have best toc on page content
    'about/resume': nosidebar_page,
    'about/resume-en': nosidebar_page,

    'blog': blog_post_page, # ABlog's "All Posts" page
    'blog/**': blog_post_page, # Inlucde posts and autogenerated pages
}

# If true, the reST sources are included in the HTML build as _sources/name.
# I don't want to public my sources, so set it to false.
html_copy_source = True

html_search_language = language

html_last_updated_fmt = datefmt

# A list of paths that contain extra files not directly related to the
# documentation.
html_extra_path = ['robots.txt', 'LICENSE']

# -- Per-extension configuration ---------------------------------------------------

extensions.append('sphinxnotes.mock')
mock_directives = []
mock_directives.append('contents') # Theme has built-in local-toc, see html_theme

extensions.append('sphinx.ext.todo')
todo_include_todos = True

extensions.append('sphinx.ext.extlinks')
extlinks = {
    'zhwiki': ('https://zh.wikipedia.org/wiki/%s', '📖 %s'),
    'enwiki': ('https://wikipedia.org/wiki/%s', '📖 %s'),
    'search': ('https://duckduckgo.com/?q=%s', '🔍 %s'),
    'twitter': ('https://twitter.com/%s', '👤 %s'),
    'ghuser': ('https://github.com/%s', '👤 %s'),
    'ghorg': ('https://github.com/%s', '👥 %s'),
    'ghrepo': ('https://github.com/%s', '⛺ %s'),
    'weibo': ('https://weibo.com/%s', '👤 %s'),
    'aur': ('https://aur.archlinux.org/packages/%s', '📦 %s'),
    'archpkg': ('https://archlinux.org/packages/%s', '📦 %s'),
    'archwiki': ('https://wiki.archlinux.org/index.php/%s', '📖 %s'),
    'zhihua': ('https://www.zhihu.com/answer/%s', '🙋 %s'),
    'zhihuq': ('https://www.zhihu.com/question/%s', '🤔 %s'),
    'zhihup': ('https://www.zhihu.com/people/%s', '👤 %s'),
    'pypi': ('https://pypi.org/project/%s', '📦 %s'),
    'lilydoc': ('https://lilypond.org/doc/v2.20/Documentation/%s', None),
    'so.q': ('https://stackoverflow.com/a/%s', '🤔 %s'),
    'so.a': ('https://stackoverflow.com/a/%s', '🙋 %s'),
    'bili': ('https://www.bilibili.com/video/%s', '🎥 %s'),
    'musicca-drum': ('https://www.musicca.com/zh/drum-machine?data=%s', '🥁 %s'),
    'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/directives.html#%s', '%s'),
    'durole': ('https://docutils.sourceforge.io/docs/ref/rst/roles.html#%s', '%s'),
}

extensions.append('sphinxnotes.any')
any_schemas = _schemas

extensions.append('ablog')
blog_path = 'blog'
blog_title = project
blog_baseurl = D.url()
blog_authors = {
    author_nick: (author, blog_baseurl),
}
blog_default_author = author_nick
blog_languages = {
    language: (language_full, None),
    # FIXME: https://github.com/sunpy/ablog/issues/136
    # 'en':     ('English',  None),
}
blog_default_language = language
post_date_format = datefmt
post_auto_image = 1
blog_feed_fulltext = True
blog_feed_subtitle = description
fontawesome_included = True
html_css_files.append('ablog-custom.css')

if D.is_public():
    extensions.append('sphinxcontrib.gtagjs')
    if D is D.Github:
        gtagjs_ids = ['G-FYHS50G6DL']
    elif D is D.Gitee:
        gtagjs_ids = ['G-5MZDR9VPYN']

if D is D.Local:
    extensions.append('sphinxnotes.snippet')
    snippet_config = {}
    snippet_patterns = {
        'd': ['.*'],
        's': ['notes/.*', 'jour/.*', 'collections/.*', 'about/.*', 'p/.*'],
        'c': ['p/.*', 'notes/man/.*'],
    }

if D.is_public():
    extensions.append('sphinxnotes.isso')
    isso_url = 'https://comments.silverrainz.me:30500'
    isso_include_patterns = ['**',]
    isso_exclude_patterns = ['index', 'ronin/**']

if D.is_public():
    extensions.append('sphinx_sitemap')
    sitemap_filename = "sitemap.xml"
    sitemap_url_scheme = "{link}"

# NOTE: required by ablog
extensions.append('sphinx.ext.intersphinx')
# Although fetching intersphinx info is slow, but we have fasthtml now.
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
    'srain': ('https://srain.silverrainz.me/', None),
}

if D.is_public():
    extensions.append('sphinx_reredirects')
    # https://documatt.gitlab.io/sphinx-reredirects/usage.html
    with open('./_conf/redirect.yml') as data:
        redirects = _redirects

# extensions.append('sphinxcontrib.images')
# images_config = {
#     'override_image_directive': True,
#     'cache_path': '_cache',
#     'download': True,
# }

extensions.append('sphinxnotes.lilypond')
lilypond_audio_volume = 300
lilypond_audio_format = 'mp3'

if D is not D.Local:
    extensions.append('sphinxnotes.recentupdate')
    recentupdate_date_format = datefmt
    recentupdate_exclude_path = ['_templates']
    recentupdate_exclude_commit = ['skip-recentupdate', 'conf']
else:
    mock_directives.append('recentupdate')

if D.is_public():
    extensions.append('sphinxext.opengraph')
    ogp_site_url = D.url()
    ogp_site_name = project
    ogp_image = D.url() + logo

if D is not D.Local:
    # Doesn't work locally
    extensions.append('notfound.extension')
    notfound_urls_prefix = ''

extensions.append('sphinxnotes.comboroles')
comboroles_roles = {
    'parsed_literal': (['literal'], True),
    'sup_abbr': ['superscript', 'abbr',],

     # for ./blog/sphinxnotes-comboroles.rst
    'strong_literal': ['strong', 'literal'],
    'literal_enwiki': ['literal', 'enwiki'],
    'literal_strike': ['literal', 'strike'],
}

extensions.append('sphinxcontrib.globalsubs')
global_substitutions = {
    '?': ':sup_abbr:`存疑 (笔者对此断言存有疑惑，请谨慎参考)`',
    'i': ':sup_abbr:`个人观点 (这是笔者的个人观点，并无权威出处，请谨慎参考)`',
    'todo': ':sup_abbr:`待补充 (但什么时候呢？)`',
    'noref': ':sup_abbr:`来源请求 (此断言也许有出处可考，但暂时无法找到)`', # citation needed

    # Marks for TODO list.
    # Role octicon: https://sphinx-design.readthedocs.io/en/latest/badges_buttons.html
    'o': ':octicon:`issue-closed;1em;sd-text-success`', # done
    '.': ':octicon:`issue-opened;1em;sd-text-warning`', # wip
    '_': ':octicon:`issue-draft`',                      # todo
    'x': ':octicon:`issue-closed;1em;sd-text-danger`',  # fail/wontdo/cancel
    'p0': ':bdg-danger:`P0`',  # priv high
    'p1': ':bdg-warning:`P1`', # priv medium
    'p2': ':bdg-info:`P2`',    # priv low

    # Abbrs.
    'rst': 'reStructuredText',
}

if D is not D.Local:
    # Speed up local build (prevent read git timestamp).
    extensions.append('sphinx_last_updated_by_git')

if D is D.Local:
    # Speed up local incremental HTML build (may cause document inconsistencies).
    extensions.append('sphinxnotes.fasthtml')