diff options
Diffstat (limited to 'docs/conf.py')
| -rw-r--r-- | docs/conf.py | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..199a32a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,169 @@ +# 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 + +from datetime import date + +from sphinx.application import Sphinx + +from myst_parser import __version__ + +# -- Project information ----------------------------------------------------- + +project = "MyST Parser" +copyright = f"{date.today().year}, Executable Book Project" +author = "Executable Book Project" +version = __version__ + +master_doc = "index" +language = "en" + +# -- 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 = [ + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx_design", + "sphinxext.rediraffe", + "sphinxcontrib.mermaid", + "sphinxext.opengraph", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# 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"] + + +# -- 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" +html_logo = "_static/logo-wide.svg" +html_favicon = "_static/logo-square.svg" +html_title = "" +html_theme_options = { + "home_page_in_toc": True, + "github_url": "https://github.com/executablebooks/MyST-Parser", + "repository_url": "https://github.com/executablebooks/MyST-Parser", + "repository_branch": "master", + "path_to_docs": "docs", + "use_repository_button": True, + "use_edit_page_button": True, +} +# OpenGraph metadata +ogp_site_url = "https://myst-parser.readthedocs.io/en/latest" +# This is the image that GitHub stores for our social media previews +ogp_image = "https://repository-images.githubusercontent.com/240151150/316bc480-cc23-11eb-96fc-4ab2f981a65d" # noqa: E501 +ogp_custom_meta_tags = [ + '<meta name="twitter:card" content="summary_large_image">', +] + +# 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"] + +myst_enable_extensions = [ + "dollarmath", + "amsmath", + "deflist", + "fieldlist", + "html_admonition", + "html_image", + "colon_fence", + "smartquotes", + "replacements", + "linkify", + "strikethrough", + "substitution", + "tasklist", + "attrs_image", +] +myst_number_code_blocks = ["typescript"] +myst_heading_anchors = 2 +myst_footnote_transition = True +myst_dmath_double_inline = True + +rediraffe_redirects = { + "using/intro.md": "sphinx/intro.md", + "sphinx/intro.md": "intro.md", + "using/use_api.md": "api/index.md", + "api/index.md": "api/reference.rst", + "using/syntax.md": "syntax/syntax.md", + "using/syntax-optional.md": "syntax/optional.md", + "using/reference.md": "syntax/reference.md", + "sphinx/reference.md": "configuration.md", + "sphinx/index.md": "faq/index.md", + "sphinx/use.md": "faq/index.md", + "sphinx/faq.md": "faq/index.md", + "explain/index.md": "develop/background.md", +} + +suppress_warnings = ["myst.strikethrough"] + + +intersphinx_mapping = { + "python": ("https://docs.python.org/3.7", None), + "sphinx": ("https://www.sphinx-doc.org/en/master", None), + "markdown_it": ("https://markdown-it-py.readthedocs.io/en/latest", None), +} + +# autodoc_default_options = { +# "show-inheritance": True, +# "special-members": "__init__, __enter__, __exit__", +# "members": True, +# # 'exclude-members': '', +# "undoc-members": True, +# # 'inherited-members': True +# } +autodoc_member_order = "bysource" +nitpicky = True +nitpick_ignore = [ + ("py:class", "docutils.nodes.document"), + ("py:class", "docutils.nodes.docinfo"), + ("py:class", "docutils.nodes.Element"), + ("py:class", "docutils.nodes.Node"), + ("py:class", "docutils.nodes.field_list"), + ("py:class", "docutils.nodes.problematic"), + ("py:class", "docutils.nodes.pending"), + ("py:class", "docutils.nodes.system_message"), + ("py:class", "docutils.statemachine.StringList"), + ("py:class", "docutils.parsers.rst.directives.misc.Include"), + ("py:class", "docutils.parsers.rst.Parser"), + ("py:class", "docutils.utils.Reporter"), + ("py:class", "nodes.Element"), + ("py:class", "nodes.Node"), + ("py:class", "nodes.system_message"), + ("py:class", "Directive"), + ("py:class", "Include"), + ("py:class", "StringList"), + ("py:class", "DocutilsRenderer"), + ("py:class", "MockStateMachine"), +] + + +def setup(app: Sphinx): + """Add functions to the Sphinx setup.""" + from myst_parser._docs import ( + DirectiveDoc, + DocutilsCliHelpDirective, + MystConfigDirective, + ) + + app.add_css_file("custom.css") + app.add_directive("myst-config", MystConfigDirective) + app.add_directive("docutils-cli-help", DocutilsCliHelpDirective) + app.add_directive("doc-directive", DirectiveDoc) |