conf.py
Examples¶
Introduction¶
The configuration directory must contain a file named conf.py
.
This file (containing Python code) is called the “build configuration file” and
contains all configuration needed to customize Sphinx input and output behavior.
The configuration file is executed as Python code at build time (using
execfile()
, and with the current directory set to its containing
directory), and therefore can execute arbitrarily complex code.
Sphinx then reads simple names from the file’s namespace as its configuration.
pypi Example¶
In your doc/source
directory is now a python file called conf.py
.
This is the file that controls the basics of how sphinx runs when you run a build. Here you can do this like:
Change the version/release number by setting the
version
andrelease
variables.Set the project name and author name.
Setup a project logo.
Set the default style to
sphinx
ordefault
. Default is what the standard python docs use.
and much much more.
Browsing through this file will give you an understanding of the basics.
Conf.py file for this project¶
. seealso:
- https://gitlab.com/gdevops/tuto_documentation/blob/master/conf.py
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 | #
# Configuration file for the Sphinx documentation builder.
# http://www.sphinx-doc.org/en/stable/config
from datetime import datetime
project = "Tuto Documentation"
author = "DevOps people"
version = "0.1.0"
release = version
now = datetime.now()
today = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H{now.minute:02}"
copyright = f"2009-{now.year}, {author}"
source_suffix = {
".rst": "restructuredtext",
".md": "markdown",
}
master_doc = "index"
language = None
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv"]
html_theme = "bizstyle"
pygments_style = "sphinx"
extensions = ["sphinx.ext.intersphinx", "recommonmark", "sphinx_tabs.tabs"]
intersphinx_mapping = {
"python": ("https://docs.python.org/", None),
"official_sphinx": ("http://www.sphinx-doc.org/", None),
"https://gdevops.gitlab.io/tuto_python/": None,
"https://gdevops.gitlab.io/tuto_django/": None,
"docker": ("https://gdevops.gitlab.io/tuto_docker/", None),
"https://gdevops.gitlab.io/tuto_cli/": None,
"https://gdevops.gitlab.io/tuto_build/": None,
"https://gdevops.gitlab.io/tuto_kubernetes/": None,
"http://blockdiag.com/en/": None,
}
extensions = extensions + ["sphinx.ext.todo"]
todo_include_todos = True
###########################################################################
# 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/master/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl
#
import importlib
import sys
import os.path
from six import string_types
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):
SUFFIX = source_suffix
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():
html_static_path = []
if os.path.exists('_static'):
html_static_path.append('_static')
# Add RTD Theme only if they aren't overriding it already
using_rtd_theme = (
(
'html_theme' in globals() and
html_theme in ['default'] and
# Allow people to bail with a hack of having an html_style
'html_style' not in globals()
) or 'html_theme' not in globals()
)
if using_rtd_theme:
theme = importlib.import_module('sphinx_rtd_theme')
html_theme = 'sphinx_rtd_theme'
html_style = None
html_theme_options = {}
if 'html_theme_path' in globals():
html_theme_path.append(theme.get_html_theme_path())
else:
html_theme_path = [theme.get_html_theme_path()]
if globals().get('websupport2_base_url', False):
websupport2_base_url = 'https://readthedocs.org/websupport'
websupport2_static_url = 'https://assets.readthedocs.org/static/'
#Add project information to the template context.
context = {
'using_theme': using_rtd_theme,
'html_theme': html_theme,
'current_version': "latest",
'version_slug': "latest",
'MEDIA_URL': "https://media.readthedocs.org/",
'STATIC_URL': "https://assets.readthedocs.org/static/",
'PRODUCTION_DOMAIN': "readthedocs.org",
'versions': [
("latest", "/en/latest/"),
("stable", "/en/stable/"),
("0.3.0", "/en/0.3.0/"),
("0.1.0", "/en/0.1.0/"),
],
'downloads': [
("pdf", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/pdf/"),
("html", "//devopstutodoc.readthedocs.io/_/downloads/en/latest/htmlzip/"),
],
'subprojects': [
],
'slug': 'devopstutodoc',
'name': u'devopstuto_doc',
'rtd_language': u'en',
'programming_language': u'py',
'canonical_url': 'https://devopstutodoc.readthedocs.io/en/latest/',
'analytics_code': '',
'single_version': False,
'conf_py_path': '/',
'api_host': 'https://readthedocs.org',
'github_user': 'None',
'github_repo': 'None',
'github_version': 'master',
'display_github': False,
'bitbucket_user': 'None',
'bitbucket_repo': 'None',
'bitbucket_version': 'master',
'display_bitbucket': False,
'gitlab_user': 'gdevops',
'gitlab_repo': 'tuto_documentation',
'gitlab_version': 'master',
'display_gitlab': True,
'READTHEDOCS': True,
'using_theme': (html_theme == "default"),
'new_theme': (html_theme == "sphinx_rtd_theme"),
'source_suffix': SUFFIX,
'ad_free': False,
'user_analytics_code': '',
'global_analytics_code': 'UA-17997319-1',
'commit': '79bea070',
}
if 'html_context' in globals():
html_context.update(context)
else:
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:
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")
project_language = 'en'
# User's Sphinx configurations
language_user = globals().get('language', None)
latex_engine_user = globals().get('latex_engine', None)
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
latex_use_xindy = False
chinese = any([
language_user in ('zh_CN', 'zh_TW'),
project_language in ('zh_CN', 'zh_TW'),
])
japanese = any([
language_user == 'ja',
project_language == 'ja',
])
if chinese:
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'
|