More detailed isort configuration explanation

[etc/vim.git] / docs / conf.py

diff --git a/docs/conf.py b/docs/conf.py
index 4a3c67c81985b27b58edf4e42119966cb7f1a4d0..9599afd599b1a1d4488c63ef53dcac1bbfcadd95 100644 (file)
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -12,13 +12,77 @@
 # 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 os
-import sys
+import ast
+from pathlib import Path
+import re
+import shutil
+import string
 
 from recommonmark.parser import CommonMarkParser
 
 
-sys.path.insert(0, os.path.abspath('.' ))
+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 -----------------------------------------------------
 
@@ -27,12 +91,15 @@ copyright = '2018, Łukasz Langa and contributors to Black'
 author = 'Łukasz Langa and contributors to Black'
 
 # Autopopulate version
-import black
-# The short X.Y version.
-# TODO: fix for 2 digit month
-version = f'{black.__version__[:4]}'
 # The full version, including alpha/beta/rc tags.
-release = black.__version__
+release = get_version()
+# The short X.Y version.
+version = release
+for sp in 'abcfr':
+    version = version.split(sp)[0]
+make_pypi_svg(release)
+generate_sections_from_readme()
+
 
 # -- General configuration ---------------------------------------------------
 
@@ -46,6 +113,7 @@ release = black.__version__
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -96,7 +164,7 @@ html_sidebars = {
 }
 
 html_theme_options = {
-    'show_related': True,
+    'show_related': False,
     'description': '“Any color you like.”',
     'github_button': True,
     'github_user': 'ambv',
@@ -204,6 +272,8 @@ epub_exclude_files = ['search.html']
 
 # -- Extension configuration -------------------------------------------------
 
+autodoc_member_order = 'bysource'
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.