Create a Sphinx Project¶
You can use your fork of the Get Started with Sphinx Repository as the start of a new project, or you can create the project by entering the command:
$ sphinx-quickstart
Work through the prompts. See First Steps with Sphinx for more information.
Sphinx Project Configuration File¶
When you create a new project with sphinx-quickstart
, the project’s main
configuration file, conf.py
is generated. This file contains the settings
that control how your project is generated.
See Sphinx Configuration for information.
The following example shows the commented conf.py
file for this project.
"""
Imports the system and the
theme the project is using to the project.
"""
import sys, os
import sphinx_bootstrap_theme
"""
Adds path to the folder ext, where extensions are stored.
"""
sys.path.append(os.path.abspath('ext'))
sys.path.append('.')
"""
Tells Sphinx which extensions to use.
"""
extensions = ['xref',
'youtube',
'sphinx.ext.autosectionlabel',
'sphinxcontrib.osexample']
"""
Imports all link files into project.
"""
from links.link import *
from links import *
"""
Tells the project where to look for theme templates and css overrides.
"""
templates_path = ['_templates']
html_static_path = ["_static"]
"""
Tells the project the name of the home page.
"""
master_doc = 'index'
"""
The project name, copyright, and author.
"""
project = u'RST | Sphinx | Sublime | GitHub'
copyright = u'2017, Mark Hoeber'
author = u'Mark Hoeber'
"""
The Google Analytics ID.
"""
googleanalytics_id = 'UA-88078032-1'
"""
Tells the project to use sphinx pygments for color coding code examples.
"""
pygments_style = 'sphinx'
"""
Tells the project to include content in todo directives. Often set through
parameter to make commands.
"""
todo_include_todos = True
"""
Tells the project which theme to use, and the theme options.
"""
html_theme = 'default'
html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
html_theme_options = {
'navbar_site_name': "Contents",
'source_link_position': "footer",
}
def setup(app):
app.add_stylesheet("my-styles.css")
"""
Tells the project to ignore certain files in the build process.
"""
exclude_patterns = ['substitutions.rst']
"""
Tells the project to append content at the end of every file during the build
process.
"""
rst_epilog = """
.. include:: substitutions.rst
"""
###########################################################################
# 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/"),
],
'downloads': [
("html", "//sublime-and-sphinx-guide.readthedocs.io/_/downloads/en/latest/htmlzip/"),
],
'subprojects': [
],
'slug': 'sublime-and-sphinx-guide',
'name': u'Sublime and Sphinx Guide',
'rtd_language': u'en',
'programming_language': u'words',
'canonical_url': 'https://sublime-and-sphinx-guide.readthedocs.io/en/latest/',
'analytics_code': '',
'single_version': False,
'conf_py_path': '/source/',
'api_host': 'https://readthedocs.org',
'github_user': 'MarkHoeber',
'proxied_api_host': '/_',
'github_repo': 'sublime_sphinx_guide',
'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': 'd3579a96',
}
# 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'):
html_baseurl = context['canonical_url']
context['canonical_url'] = None
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")
readthedocs_vcs_url = 'None'
readthedocs_build_url = 'https://readthedocs.org/projects/sublime-and-sphinx-guide/builds/13104311/'
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'
# Make sure our build directory is always excluded
exclude_patterns = globals().get('exclude_patterns', [])
exclude_patterns.extend(['_build'])