diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 0ebdd74410e..7c888ea3484 100644 --- a/docs/.rstcheck.cfg +++ b/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) diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index ae65d8e4221..57b552abd73 100644 --- a/docs/doc_extensions.py +++ b/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', diff --git a/docs/faq.rst b/docs/faq.rst index 30025963c18..2428f9e2431 100644 --- a/docs/faq.rst +++ b/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 `. + +.. _github: https://github.com/rtfd/readthedocs.org + I get import errors on libraries that depend on C modules --------------------------------------------------------- diff --git a/docs/guides/feature-flags.rst b/docs/guides/feature-flags.rst new file mode 100644 index 00000000000..92600286b94 --- /dev/null +++ b/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`