# -*- coding: utf-8 -*-
#
# 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.
#
"""Configuration file for the documentation."""
import pathlib
import time
# Load the dummy profile even if we are running locally, this way the documentation will succeed even if the current
# default profile of the AiiDA installation does not use a Django backend.
from aiida.manage.configuration import Profile, load_profile
load_profile(Profile('docs', {'process_control': {}, 'storage': {}}))
# 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.
import aiida_yambo
# -- Project information -----------------------------------------------------
[docs]copyright = u'2015-{}, ECOLE POLYTECHNIQUE FEDERALE DE LAUSANNE (Theory and Simulation of Materials (THEOS) and National Centre for Computational Design and Discovery of Novel Materials (NCCR MARVEL)), Switzerland and CNR NANO Modena, Italy. All rights reserved.'.format(
time.localtime().tm_year)
# The full version, including alpha/beta/rc tags.
[docs]release = aiida_yambo.__version__
# The short X.Y version.
[docs]version = '.'.join(aiida_yambo.__version__.split('.')[:2])
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'myst_nb',
'sphinx.ext.autodoc',
'sphinx.ext.mathjax',
'sphinx.ext.intersphinx',
'sphinx.ext.viewcode',
'sphinx_copybutton',
'sphinx_togglebutton',
'sphinx_design',
'aiida.sphinxext',
'autoapi.extension',
]
# Setting the intersphinx mapping to other readthedocs
[docs]intersphinx_mapping = {
'python': ('https://docs.python.org/3.8', None),
'aiida': ('https://aiida.readthedocs.io/en/latest/', None),
'aiida_pseudo': ('https://aiida-pseudo.readthedocs.io/en/latest/', None),
'matplotlib': ('https://matplotlib.org/stable/', None),
'aiida_quantumespresso': ('https://aiida-quantumespresso.readthedocs.io/en/latest/', None),
'sphinx': ('https://www.sphinx-doc.org/en/master', None),
}
[docs]myst_enable_extensions = [
'amsmath',
'deflist',
'colon_fence',
'substitution',
'dollarmath',
'html_image',
]
[docs]myst_substitutions = {
'release': release,
'version': version,
}
[docs]source_suffix = {
'.rst': 'restructuredtext',
'.md': 'myst-nb',
'.ipynb': 'myst-nb',
'.myst': 'myst-nb',
}
# Don't run the already executed notebooks
[docs]nb_execution_mode = 'off' # cache
# Execution timeout (seconds)
[docs]nb_execution_timeout = 600
# Settings for the `autoapi.extenstion` automatically generating API docs
[docs]filepath_docs = pathlib.Path(__file__).parent.parent
[docs]filepath_src = filepath_docs.parent #/ 'src'
[docs]autoapi_dirs = [filepath_src]
[docs]autoapi_ignore = [filepath_src / 'aiida_yambo' / '*cli*']
[docs]autoapi_root = str(filepath_docs / 'source' / 'reference' / 'api')
[docs]autoapi_keep_files = True
[docs]autoapi_add_toctree_entry = False
# Settings for the `sphinx_copybutton` extension
[docs]copybutton_prompt_text = r'>>> |\.\.\. |(?:\(.*\) )?\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: '
# Add any paths that contain templates here, relative to this directory.
[docs]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 = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# -- 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_book_theme'
[docs]html_theme_options = {
'repository_url': 'https://github.com/yambo-code/aiida-yambo',
'github_url': 'https://github.com/yambo-code/aiida-yambo',
'use_edit_page_button': True,
'use_download_button': True,
'use_sidenotes': True,
'logo': {
'text': 'AiiDA yambo',
#'image_light': '_static/aiida-yambo-logo.png',
#'image_dark': '_static/aiida-yambo-logo.png',
'image_light': '_static/yambo-aiida-event_logo_v1.4.svg',
'image_dark': '_static/yambo-aiida-event_logo_v1.4.svg',
},
}
#html_static_path = ['_static']
html_context = {
'github_user': 'mikibonacci',
'github_repo': 'aiida-yambo',
'github_version': 'master',
'doc_path': 'docs/source',
'default_mode': 'light',
}
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = 'images/yambo_logo.png'
html_static_path = ['_static']
[docs]html_css_files = ['aiida-custom.css', 'aiida-qe-custom.css']
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
[docs]html_use_opensearch = 'http://aiida-yambo.readthedocs.io'
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
[docs]html_search_language = 'en'
# Output file base name for HTML help builder.
[docs]htmlhelp_basename = 'aiida-yambodoc'
# -- Options for LaTeX output ---------------------------------------------
[docs]latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# 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 = [
# ]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
# man_pages = [
# ]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
# texinfo_documents = [
# ]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# Warnings to ignore when using the -n (nitpicky) option
# We should ignore any python built-in exception, for instance
[docs]nitpick_ignore = [
('py:exc', 'ArithmeticError'),
('py:exc', 'AssertionError'),
('py:exc', 'AttributeError'),
('py:exc', 'BaseException'),
('py:exc', 'BufferError'),
('py:exc', 'DeprecationWarning'),
('py:exc', 'EOFError'),
('py:exc', 'EnvironmentError'),
('py:exc', 'Exception'),
('py:exc', 'FloatingPointError'),
('py:exc', 'FutureWarning'),
('py:exc', 'GeneratorExit'),
('py:exc', 'IOError'),
('py:exc', 'ImportError'),
('py:exc', 'ImportWarning'),
('py:exc', 'IndentationError'),
('py:exc', 'IndexError'),
('py:exc', 'KeyError'),
('py:exc', 'KeyboardInterrupt'),
('py:exc', 'LookupError'),
('py:exc', 'MemoryError'),
('py:exc', 'NameError'),
('py:exc', 'NotImplementedError'),
('py:exc', 'OSError'),
('py:exc', 'OverflowError'),
('py:exc', 'PendingDeprecationWarning'),
('py:exc', 'ReferenceError'),
('py:exc', 'RuntimeError'),
('py:exc', 'RuntimeWarning'),
('py:exc', 'StandardError'),
('py:exc', 'StopIteration'),
('py:exc', 'SyntaxError'),
('py:exc', 'SyntaxWarning'),
('py:exc', 'SystemError'),
('py:exc', 'SystemExit'),
('py:exc', 'TabError'),
('py:exc', 'TypeError'),
('py:exc', 'UnboundLocalError'),
('py:exc', 'UnicodeDecodeError'),
('py:exc', 'UnicodeEncodeError'),
('py:exc', 'UnicodeError'),
('py:exc', 'UnicodeTranslateError'),
('py:exc', 'UnicodeWarning'),
('py:exc', 'UserWarning'),
('py:exc', 'VMSError'),
('py:exc', 'ValueError'),
('py:exc', 'Warning'),
('py:exc', 'WindowsError'),
('py:exc', 'ZeroDivisionError'),
('py:obj', 'str'),
('py:obj', 'list'),
('py:obj', 'tuple'),
('py:obj', 'int'),
('py:obj', 'float'),
('py:obj', 'bool'),
('py:obj', 'Mapping'),
('py:obj', 'qe_tools.parsers.CpInputFile'),
('py:obj', 'qe_tools.parsers.PwInputFile'),
('py:class', 'StructureData'),
('py:class', 'PseudoPotentialFamily'),
]
[docs]nitpick_ignore_regex = [
(r'py:.*', key) for key in [
r'data.*',
r'aiida.*',
r'orm.*',
r'phonopy.*',
r'numpy.*',
r'np.*',
r'pydantic.*',
]
]
###########################################################################
# auto-created readthedocs.org specific configuration #
###########################################################################
#
# The following code was added during an automated build on readthedocs.org
# It is auto created and injected for every build. The result is based on the
# conf.py.tmpl file found in the readthedocs.org codebase:
# https://github.com/rtfd/readthedocs.org/blob/main/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
#
# Note: this file shouldn't rely on extra dependencies.
import importlib
import sys
import os.path
# Borrowed from six.
[docs]PY3 = sys.version_info[0] == 3
[docs]string_types = str if PY3 else basestring
from sphinx import version_info
# Get suffix for proper linking to GitHub
# This is deprecated in Sphinx 1.3+,
# as each page can have its own suffix
if globals().get('source_suffix', False):
if isinstance(source_suffix, string_types):
elif isinstance(source_suffix, (list, tuple)):
# Sphinx >= 1.3 supports list/tuple to define multiple suffixes
SUFFIX = source_suffix[0]
elif isinstance(source_suffix, dict):
# Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes
SUFFIX = list(source_suffix.keys())[0] # make a ``list()`` for py2/py3 compatibility
else:
# default to .rst
SUFFIX = '.rst'
else:
SUFFIX = '.rst'
# Add RTD Static Path. Add to the end because it overwrites previous files.
if not 'html_static_path' in globals():
if os.path.exists('_static'):
html_static_path.append('_static')
# Define this variable in case it's not defined by the user.
# It defaults to `alabaster` which is the default from Sphinx.
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme
[docs]html_theme = globals().get('html_theme', 'alabaster')
#Add project information to the template context.
[docs]context = {
'html_theme': html_theme,
'current_version': "master",
'version_slug': "master",
'MEDIA_URL': "https://media.readthedocs.org/",
'STATIC_URL': "https://assets.readthedocs.org/static/",
'PRODUCTION_DOMAIN': "readthedocs.org",
'proxied_static_path': "/_/static/",
'versions': [
("master", "/en/master/"),
("v1.1.1", "/en/v1.1.1/"),
("v1.0.2", "/en/v1.0.2/"),
("v1.0.0", "/en/v1.0.0/"),
("documentation", "/en/documentation/"),
("docs", "/en/docs/"),
("develop", "/en/develop/"),
],
'downloads': [
],
'subprojects': [
],
'slug': 'aiida-yambo',
'name': u'aiida-yambo',
'rtd_language': u'en',
'programming_language': u'py',
'canonical_url': '',
'analytics_code': 'None',
'single_version': False,
'conf_py_path': '/docs/source/',
'api_host': 'https://readthedocs.org',
'github_user': 'yambo-code',
'proxied_api_host': '/_',
'github_repo': 'yambo-aiida',
'github_version': 'master',
'display_github': True,
'bitbucket_user': 'None',
'bitbucket_repo': 'None',
'bitbucket_version': 'master',
'display_bitbucket': False,
'gitlab_user': 'None',
'gitlab_repo': 'None',
'gitlab_version': 'master',
'display_gitlab': False,
'READTHEDOCS': True,
'using_theme': (html_theme == "default"),
'new_theme': (html_theme == "sphinx_rtd_theme"),
'source_suffix': SUFFIX,
'ad_free': False,
'docsearch_disabled': False,
'user_analytics_code': '',
'global_analytics_code': 'UA-17997319-1',
'commit': 'c193f16e',
}
# For sphinx >=1.8 we can use html_baseurl to set the canonical URL.
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl
if version_info >= (1, 8):
if not globals().get('html_baseurl'):
[docs] html_baseurl = context['canonical_url']
context['canonical_url'] = None
if 'html_context' in globals():
for key in context:
if key not in html_context:
html_context[key] = context[key]
else:
[docs] html_context = context
# Add custom RTD extension
if 'extensions' in globals():
# Insert at the beginning because it can interfere
# with other extensions.
# See https://github.com/rtfd/readthedocs.org/pull/4054
extensions.insert(0, "readthedocs_ext.readthedocs")
else:
[docs] extensions = ["readthedocs_ext.readthedocs"]
# Add External version warning banner to the external version documentation
if 'branch' == 'external':
extensions.insert(1, "readthedocs_ext.external_version_warning")
[docs] readthedocs_vcs_url = 'None'
readthedocs_build_url = 'https://readthedocs.org/projects/aiida-yambo/builds/23585121/'
# User's Sphinx configurations
[docs]language_user = globals().get('language', None)
[docs]latex_engine_user = globals().get('latex_engine', None)
[docs]latex_elements_user = globals().get('latex_elements', None)
# Remove this once xindy gets installed in Docker image and XINDYOPS
# env variable is supported
# https://github.com/rtfd/readthedocs-docker-images/pull/98
[docs]chinese = any([
language_user in ('zh_CN', 'zh_TW'),
project_language in ('zh_CN', 'zh_TW'),
])
[docs]japanese = any([
language_user == 'ja',
project_language == 'ja',
])
if chinese:
[docs] latex_engine = latex_engine_user or 'xelatex'
latex_elements_rtd = {
'preamble': '\\usepackage[UTF8]{ctex}\n',
}
latex_elements = latex_elements_user or latex_elements_rtd
elif japanese:
latex_engine = latex_engine_user or 'platex'
# Make sure our build directory is always excluded
[docs]exclude_patterns = globals().get('exclude_patterns', [])
exclude_patterns.extend(['_build'])
