Merge pull request #5043 from dojutsu-user/docs-for-feature-flags

Docs for feature flag

Author: ericholscher

docs/.rstcheck.cfg

@@ -1,4 +1,4 @@
 [rstcheck]
 ignore_directives=automodule,http:get,tabs,tab,prompt
-ignore_roles=djangosetting,setting
+ignore_roles=djangosetting,setting,featureflags
 ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced)

docs/doc_extensions.py

@@ -12,6 +12,8 @@
 
 from django.conf import settings
 
+from readthedocs.projects.models import Feature
+
 
 def django_setting_role(typ, rawtext, text, lineno, inliner, options=None,
                         content=None):
@@ -21,9 +23,27 @@ def django_setting_role(typ, rawtext, text, lineno, inliner, options=None,
     return [node], []
 
 
+def feature_flags_role(typ, rawtext, text, lineno, inliner, options=None,
+                        content=None):
+    """Up to date feature flags from the application."""
+    all_features = Feature.FEATURES
+    requested_feature = utils.unescape(text)
+    for feature in all_features:
+        if requested_feature.lower() == feature[0].lower():
+            desc = nodes.Text(feature[1], feature[1])
+    return [desc], []
+
+
 def setup(_):
     from docutils.parsers.rst import roles
-    roles.register_local_role('djangosetting', django_setting_role)
+    roles.register_local_role(
+        'djangosetting',
+        django_setting_role
+    )
+    roles.register_local_role(
+        'featureflags',
+        feature_flags_role
+    )
 
     return {
         'version': 'builtin',

docs/faq.rst

@@ -64,6 +64,16 @@ environment, and will be set to ``True`` when building on RTD::
     Woo
     {% endif %}
 
+My project requires different settings than those available under Admin
+-----------------------------------------------------------------------
+
+Read the Docs offers some settings which can be used for a variety of purposes,
+such as to use the latest version of sphinx or pip. To enable these settings,
+please open a request issue on our `github`_ and we will change the settings for the project.
+Read more about these settings :doc:`here <guides/feature-flags>`.
+
+.. _github: https://github.com/rtfd/readthedocs.org
+
 I get import errors on libraries that depend on C modules
 ---------------------------------------------------------
 

docs/guides/feature-flags.rst

@@ -0,0 +1,31 @@
+Feature Flags
+=============
+
+Read the Docs offers some additional flag settings which can be only be configured by the site admin.
+These are optional settings and you might not need it for every project.
+By default, these flags are disabled for every project.
+A seperate request can be made by opening an issue on our `github`_ to enable
+or disable one or more of these featured flags for a particular project.
+
+.. _github: https://github.com/rtfd/readthedocs.org
+
+Available Flags
+---------------
+
+``USE_SPHINX_LATEST``: :featureflags:`USE_SPHINX_LATEST`
+
+``USE_SETUPTOOLS_LATEST``: :featureflags:`USE_SETUPTOOLS_LATEST`
+
+``ALLOW_DEPRECATED_WEBHOOKS``: :featureflags:`ALLOW_DEPRECATED_WEBHOOKS`
+
+``PIP_ALWAYS_UPGRADE``: :featureflags:`PIP_ALWAYS_UPGRADE`
+
+``SKIP_SUBMODULES``: :featureflags:`SKIP_SUBMODULES`
+
+``DONT_OVERWRITE_SPHINX_CONTEXT``: :featureflags:`DONT_OVERWRITE_SPHINX_CONTEXT`
+
+``ALLOW_V2_CONFIG_FILE``: :featureflags:`ALLOW_V2_CONFIG_FILE`
+
+``MKDOCS_THEME_RTD``: :featureflags:`MKDOCS_THEME_RTD`
+
+``DONT_SHALLOW_CLONE``: :featureflags:`DONT_SHALLOW_CLONE`