Add version warning extension (#1523)

dotnet · Jun 26, 2016 · 08cefb4 · 08cefb4
1 parent 35072bd
commit 08cefb4
Show file tree

Hide file tree

Showing 29 changed files with 117 additions and 4 deletions.
diff --git a/.gitignore b/.gitignore
@@ -200,3 +200,4 @@ FakesAssemblies/
 project.lock.json
 **/sample/**/wwwroot/lib/
 **/samples/**/wwwroot/lib/
+__pycache__/
diff --git a/aspnet/client-side/angular.rst b/aspnet/client-side/angular.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Using Angular for Single Page Applications (SPAs)
 =================================================
 

diff --git a/aspnet/client-side/bundling-and-minification.rst b/aspnet/client-side/bundling-and-minification.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc2
+
 Bundling and Minification
 =========================
 

diff --git a/aspnet/conf.py b/aspnet/conf.py
@@ -30,9 +30,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+sys.path.append(os.path.abspath('ext'))
+
 extensions = [
     'sphinx.ext.intersphinx',
-    'sphinxcontrib.dotnetdomain']
+    'sphinxcontrib.dotnetdomain',
+    'versionwarning']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates', '../common/_templates']
@@ -56,7 +59,7 @@
 # built documents.
 #
 # The short X.Y version.
-# version = '0.0.1'
+version = '1.0.0'
 # The full version, including alpha/beta/rc tags.
 # release = '0.0.1'
 
@@ -374,3 +377,4 @@ def setup(app):
     'api': ('http://docs.asp.net/projects/api/en/latest', '../common/api.inv')
 }
 
+versionwarning_console = False
diff --git a/aspnet/ext/versionwarning.py b/aspnet/ext/versionwarning.py
@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""
+Add the ability to specify the version for a specific page.
+
+This allows you to put metadata at the top of your document::
+
+    :version: 2.3
+
+This version should be the version of the project that this page or API targets.
+
+If you configure ``versionwarning_node`` to True (default),
+then it will generate an in-page warning for out of date versions.
+
+If you configure ``versionwarning_console`` to True (default),
+then it will output a warning on the console.
+"""
+
+
+from collections import defaultdict
+
+from sphinx.util.console import red, bold
+from docutils import nodes
+
+
+def process_meta(app, doctree, fromdocname):
+    env = app.builder.env
+    env.page_to_version = defaultdict(set)
+    env.version_to_page = defaultdict(set)
+
+    # index metadata
+    for pagename, metadata in iter(env.metadata.items()):
+        if 'version' in metadata:
+            version = metadata['version']
+            env.page_to_version[pagename] = version
+            env.version_to_page[version].add(pagename)
+
+            if fromdocname == pagename:
+
+                # Alert on outdated version
+                current_version = env.config['version']
+                if version != current_version:
+                    text = 'This page documents version {old} and has not yet been updated for version {new}'.format(
+                        old=version,
+                        new=current_version,
+                    )
+
+                    if app.config['versionwarning_node']:
+                        prose = nodes.paragraph(text, text)
+                        warning = nodes.warning(prose, prose)
+                        doctree.insert(0, warning)
+                    if app.config['versionwarning_console']:
+                        app.warn(bold('[Version Warning: %s] ' % pagename) + red(text))
+
+
+def setup(app):
+    app.connect('doctree-resolved', process_meta)
+    app.add_config_value('versionwarning_node', True, 'html')
+    app.add_config_value('versionwarning_console', True, 'html')
diff --git a/aspnet/fundamentals/app-state.rst b/aspnet/fundamentals/app-state.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Managing Application State
 ==========================
 

diff --git a/aspnet/fundamentals/dependency-injection.rst b/aspnet/fundamentals/dependency-injection.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc2
+
 .. _fundamentals-dependency-injection:
 
 Dependency Injection

diff --git a/aspnet/fundamentals/environments.rst b/aspnet/fundamentals/environments.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Working with Multiple Environments
 ==================================
 

diff --git a/aspnet/fundamentals/error-handling.rst b/aspnet/fundamentals/error-handling.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Error Handling
 ==============
 

diff --git a/aspnet/fundamentals/owin.rst b/aspnet/fundamentals/owin.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 OWIN
 ====
 

diff --git a/aspnet/fundamentals/routing.rst b/aspnet/fundamentals/routing.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc2
+
 Routing
 =======
 By `Steve Smith`_

diff --git a/aspnet/fundamentals/servers.rst b/aspnet/fundamentals/servers.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Servers
 =======
 

diff --git a/aspnet/migration/http-modules.rst b/aspnet/migration/http-modules.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Migrating HTTP Modules to Middleware
 ====================================
 

diff --git a/aspnet/migration/http-modules/sample/Asp.Net5/src/Asp.Net5/project.json b/aspnet/migration/http-modules/sample/Asp.Net5/src/Asp.Net5/project.json
@@ -13,7 +13,7 @@
     "Microsoft.AspNet.Server.Kestrel": "1.0.0-rc1-final",
     "Microsoft.AspNet.StaticFiles": "1.0.0-rc1-final",
     "Microsoft.AspNet.Tooling.Razor": "1.0.0-rc1-final",
-    "Microsoft.AspNetCore.Http": "1.0.0-rc2-16272",
+    "Microsoft.AspNet.Http": "1.0.0-rc1-final",
     "Microsoft.Extensions.Configuration.FileProviderExtensions": "1.0.0-rc1-final",
     "Microsoft.Extensions.Configuration.Json": "1.0.0-rc1-final",
     "Microsoft.Extensions.Logging": "1.0.0-rc1-final",

diff --git a/aspnet/migration/mvc.rst b/aspnet/migration/mvc.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc2
+
 Migrating From ASP.NET MVC to ASP.NET Core MVC
 ================================================
 

diff --git a/aspnet/migration/webapi.rst b/aspnet/migration/webapi.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Migrating from ASP.NET Web API
 ==============================
 

diff --git a/aspnet/mvc/controllers/dependency-injection.rst b/aspnet/mvc/controllers/dependency-injection.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 .. _dependency-injection-controllers:
 
 Dependency Injection and Controllers

diff --git a/aspnet/mvc/controllers/testing.rst b/aspnet/mvc/controllers/testing.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Testing Controller Logic
 ========================
 By `Steve Smith`_

diff --git a/aspnet/mvc/views/partial.rst b/aspnet/mvc/views/partial.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc2
+
 Partial Views
 =============
 

diff --git a/aspnet/mvc/views/view-components.rst b/aspnet/mvc/views/view-components.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 View Components
 ================
 

diff --git a/aspnet/mvc/views/working-with-forms.rst b/aspnet/mvc/views/working-with-forms.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Working with Forms 
 ====================
 

diff --git a/aspnet/performance/caching/distributed.rst b/aspnet/performance/caching/distributed.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Working with a Distributed Cache
 ================================
 

diff --git a/aspnet/performance/caching/memory.rst b/aspnet/performance/caching/memory.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc2
+
 In Memory Caching
 =================
 

diff --git a/aspnet/performance/caching/response.rst b/aspnet/performance/caching/response.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Response Caching
 ================
 

diff --git a/aspnet/security/authentication/2fa.rst b/aspnet/security/authentication/2fa.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-beta8
+
 .. _security-authentication-2fa:
 
 Two-factor authentication with SMS

diff --git a/aspnet/security/authentication/accconfirm.rst b/aspnet/security/authentication/accconfirm.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-beta7
+
 .. _security-authentication-account-confirmation:
 
 Account Confirmation and Password Recovery

diff --git a/aspnet/security/cors.rst b/aspnet/security/cors.rst
@@ -1,4 +1,6 @@
-Enabling Cross-Origin Requests (CORS)
+:version: 1.0.0-rc1
+
+Enabling Cross-Origin Requests (CORS)
 =====================================
 
 By `Mike Wasson`_

diff --git a/aspnet/testing/integration-testing.rst b/aspnet/testing/integration-testing.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc1
+
 Integration Testing
 ===================
 

diff --git a/aspnet/testing/unit-testing.rst b/aspnet/testing/unit-testing.rst
@@ -1,3 +1,5 @@
+:version: 1.0.0-rc2
+
 Unit Testing
 ============