]> git.madduck.net Git - etc/vim.git/blobdiff - docs/conf.py

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

line_length=1 to reduce churn (#1092)
[etc/vim.git] / docs / conf.py
index 19a161b6bce6ce29cbef015e8587e7dd67d7de74..ce7536defbd6417be7c62c8fcbbba3c899bc41b0 100644 (file)
 # 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.
 #
 # 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 ast
 from pathlib import Path
 from pathlib import Path
-import re
+import regex as re
+import shutil
+import string
 
 
+from setuptools_scm import get_version
 from recommonmark.parser import CommonMarkParser
 
 
 CURRENT_DIR = Path(__file__).parent
 
 
 from recommonmark.parser import CommonMarkParser
 
 
 CURRENT_DIR = Path(__file__).parent
 
 
-def get_version():
-    black_py = CURRENT_DIR / '..' / 'black.py'
-    _version_re = re.compile(r'__version__\s+=\s+(?P<version>.*)')
-    with open(str(black_py), 'r', encoding='utf8') as f:
-        version = _version_re.search(f.read()).group('version')
-    return str(ast.literal_eval(version))
+def make_pypi_svg(version):
+    template = CURRENT_DIR / "_static" / "pypi_template.svg"
+    target = CURRENT_DIR / "_static" / "pypi.svg"
+    with open(str(template), "r", encoding="utf8") as f:
+        svg = string.Template(f.read()).substitute(version=version)
+    with open(str(target), "w", encoding="utf8") as f:
+        f.write(svg)
+
+
+def make_filename(line):
+    non_letters = re.compile(r"[^a-z]+")
+    filename = line[3:].rstrip().lower()
+    filename = non_letters.sub("_", filename)
+    if filename.startswith("_"):
+        filename = filename[1:]
+    if filename.endswith("_"):
+        filename = filename[:-1]
+    return filename + ".md"
+
+
+def generate_sections_from_readme():
+    target_dir = CURRENT_DIR / "_build" / "generated"
+    readme = CURRENT_DIR / ".." / "README.md"
+    shutil.rmtree(str(target_dir), ignore_errors=True)
+    target_dir.mkdir(parents=True)
+
+    output = None
+    target_dir = target_dir.relative_to(CURRENT_DIR)
+    with open(str(readme), "r", encoding="utf8") as f:
+        for line in f:
+            if line.startswith("## "):
+                if output is not None:
+                    output.close()
+                filename = make_filename(line)
+                output_path = CURRENT_DIR / filename
+                if output_path.is_symlink() or output_path.is_file():
+                    output_path.unlink()
+                output_path.symlink_to(target_dir / filename)
+                output = open(str(output_path), "w", encoding="utf8")
+                output.write(
+                    "[//]: # (NOTE: THIS FILE IS AUTOGENERATED FROM README.md)\n\n"
+                )
+
+            if output is None:
+                continue
+
+            if line.startswith("##"):
+                line = line[1:]
+
+            output.write(line)
 
 
 # -- Project information -----------------------------------------------------
 
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'Black'
-copyright = '2018, Łukasz Langa and contributors to Black'
-author = 'Łukasz Langa and contributors to Black'
+project = "Black"
+copyright = "2018, Łukasz Langa and contributors to Black"
+author = "Łukasz Langa and contributors to Black"
 
 # Autopopulate version
 # The full version, including alpha/beta/rc tags.
 
 # Autopopulate version
 # The full version, including alpha/beta/rc tags.
-release = get_version()
+release = get_version(root=CURRENT_DIR.parent)
 # The short X.Y version.
 version = release
 # The short X.Y version.
 version = release
-for sp in 'abcfr':
+for sp in "abcfr":
     version = version.split(sp)[0]
     version = version.split(sp)[0]
+make_pypi_svg(release)
+generate_sections_from_readme()
+
 
 # -- General configuration ---------------------------------------------------
 
 
 # -- General configuration ---------------------------------------------------
 
@@ -53,24 +102,19 @@ for sp in 'abcfr':
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 # 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.autodoc',
-    'sphinx.ext.intersphinx',
-]
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.napoleon"]
 
 # Add any paths that contain templates here, relative to this directory.
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 
-source_parsers = {
-    '.md': CommonMarkParser,
-}
+source_parsers = {".md": CommonMarkParser}
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-source_suffix = ['.rst', '.md']
+source_suffix = [".rst", ".md"]
 
 # The master toctree document.
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -82,10 +126,10 @@ language = None
 # 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 .
 # 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']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 
 # -- Options for HTML output -------------------------------------------------
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -93,35 +137,36 @@ pygments_style = 'sphinx'
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = "alabaster"
 
 html_sidebars = {
 
 html_sidebars = {
-    '**': [
-        'about.html',
-        'navigation.html',
-        'relations.html',
-        'sourcelink.html',
-        'searchbox.html'
+    "**": [
+        "about.html",
+        "navigation.html",
+        "relations.html",
+        "sourcelink.html",
+        "searchbox.html",
     ]
 }
 
 html_theme_options = {
     ]
 }
 
 html_theme_options = {
-    'show_related': False,
-    'description': '“Any color you like.”',
-    'github_button': True,
-    'github_user': 'ambv',
-    'github_repo': 'black',
-    'github_type': 'star',
-    'show_powered_by': True,
-    'fixed_sidebar': True,
-    'logo': 'logo2.png',
+    "show_related": False,
+    "description": "“Any color you like.”",
+    "github_button": True,
+    "github_user": "psf",
+    "github_repo": "black",
+    "github_type": "star",
+    "show_powered_by": True,
+    "fixed_sidebar": True,
+    "logo": "logo2.png",
+    "travis_button": True,
 }
 
 
 # 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".
 }
 
 
 # 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_static_path = ["_static"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -137,7 +182,7 @@ html_static_path = ['_static']
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
 # -- Options for HTMLHelp output ---------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'blackdoc'
+htmlhelp_basename = "blackdoc"
 
 
 # -- Options for LaTeX output ------------------------------------------------
 
 
 # -- Options for LaTeX output ------------------------------------------------
@@ -146,15 +191,12 @@ latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
     # Additional stuff for the LaTeX preamble.
     #
     # 'preamble': '',
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
@@ -164,8 +206,13 @@ latex_elements = {
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'black.tex', 'Documentation for Black',
-     'Łukasz Langa and contributors to Black', 'manual'),
+    (
+        master_doc,
+        "black.tex",
+        "Documentation for Black",
+        "Łukasz Langa and contributors to Black",
+        "manual",
+    )
 ]
 
 
 ]
 
 
@@ -173,10 +220,7 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'black', 'Documentation for Black',
-     [author], 1)
-]
+man_pages = [(master_doc, "black", "Documentation for Black", [author], 1)]
 
 
 # -- Options for Texinfo output ----------------------------------------------
 
 
 # -- Options for Texinfo output ----------------------------------------------
@@ -185,9 +229,15 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'Black', 'Documentation for Black',
-     author, 'Black', 'The uncompromising Python code formatter',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "Black",
+        "Documentation for Black",
+        author,
+        "Black",
+        "The uncompromising Python code formatter",
+        "Miscellaneous",
+    )
 ]
 
 
 ]
 
 
@@ -209,12 +259,14 @@ epub_copyright = copyright
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
 # epub_uid = ''
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 
 # -- Extension configuration -------------------------------------------------
 
 
 
 # -- Extension configuration -------------------------------------------------
 
+autodoc_member_order = "bysource"
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3/': None}
+intersphinx_mapping = {"https://docs.python.org/3/": None}