From 3fbe47dc2bc17477a128b99e2762f3f517d6eb79 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Thu, 27 Dec 2018 22:30:27 +0530 Subject: [PATCH 1/9] Add feature-flags page --- docs/guides/feature-flags.rst | 59 +++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/guides/feature-flags.rst diff --git a/docs/guides/feature-flags.rst b/docs/guides/feature-flags.rst new file mode 100644 index 00000000000..7889927ad16 --- /dev/null +++ b/docs/guides/feature-flags.rst @@ -0,0 +1,59 @@ +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: +~~~~~~~~~~~~~~~~~~ + +Use latest version of Sphinx in building the project. + +USE_SETUPTOOLS_LATEST: +~~~~~~~~~~~~~~~~~~~~~~ + +Use latest version of setuptools in building the project. + +ALLOW_DEPRECATED_WEBHOOKS: +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Allow deprecated webhook views. + +PIP_ALWAYS_UPGRADE: +~~~~~~~~~~~~~~~~~~~ + +Always run: + +.. code-block:: bash + + pip install --upgrade + +before building the project. + +SKIP_SUBMODULES: +~~~~~~~~~~~~~~~~ + +Skip git submodule checkout. + +DONT_OVERWRITE_SPHINX_CONTEXT: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Do not overwrite context vars in conf.py with Read the Docs context. + +ALLOW_V2_CONFIG_FILE: +~~~~~~~~~~~~~~~~~~~~~ + +Allow to use the v2 of the configuration file. + +MKDOCS_THEME_RTD: +~~~~~~~~~~~~~~~~~ + +Use Read the Docs theme for MkDocs as default theme. From 4adef9ec627218626b139728de6d39bdb4762a89 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Thu, 27 Dec 2018 22:30:40 +0530 Subject: [PATCH 2/9] add ques on faq --- docs/faq.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/faq.rst b/docs/faq.rst index 30025963c18..81459059576 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 that are available under Admin +-------------------------------------------------------------------------- + +Read the Docs offers additional flag settings. To enable these settings, please open an +request issue on our `github`_ and we will change the settings for the project. Read more about +these flag settings +:ref:`here Date: Fri, 28 Dec 2018 15:34:09 +0530 Subject: [PATCH 3/9] Add the forgotten > --- docs/faq.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/faq.rst b/docs/faq.rst index 81459059576..b0face20e63 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -70,7 +70,7 @@ My project requires different settings than that are available under Admin Read the Docs offers additional flag settings. To enable these settings, please open an request issue on our `github`_ and we will change the settings for the project. Read more about these flag settings -:ref:`here `. .. _github: https://github.com/rtfd/readthedocs.org From c7c73704a6249c50fae9496434478db43b7046cd Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Fri, 28 Dec 2018 15:51:24 +0530 Subject: [PATCH 4/9] fix relative link --- docs/faq.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index b0face20e63..51ac514989e 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -69,8 +69,7 @@ My project requires different settings than that are available under Admin Read the Docs offers additional flag settings. To enable these settings, please open an request issue on our `github`_ and we will change the settings for the project. Read more about -these flag settings -:ref:`here `. +these flag settings :doc:`here `. .. _github: https://github.com/rtfd/readthedocs.org From 534026db6aa67afb2492fade325cd9036cf8ebc0 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Wed, 2 Jan 2019 21:15:46 +0530 Subject: [PATCH 5/9] add improvements --- docs/faq.rst | 8 ++++---- docs/guides/feature-flags.rst | 10 +++++----- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index 51ac514989e..3211777ecf0 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -64,12 +64,12 @@ environment, and will be set to ``True`` when building on RTD:: Woo {% endif %} -My project requires different settings than that are available under Admin +My project requires different settings than those available under Admin -------------------------------------------------------------------------- -Read the Docs offers additional flag settings. To enable these settings, please open an -request issue on our `github`_ and we will change the settings for the project. Read more about -these flag settings :doc:`here `. +Read the Docs offers additional flag settings. 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 flag settings :doc:`here `. .. _github: https://github.com/rtfd/readthedocs.org diff --git a/docs/guides/feature-flags.rst b/docs/guides/feature-flags.rst index 7889927ad16..d0fdc41bd56 100644 --- a/docs/guides/feature-flags.rst +++ b/docs/guides/feature-flags.rst @@ -1,11 +1,11 @@ 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. +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 From 9bbd946a4b9fb5f3de307cf5be719082ea1dfcfb Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Thu, 3 Jan 2019 22:33:36 +0530 Subject: [PATCH 6/9] implement rst role --- docs/.rstcheck.cfg | 2 +- docs/doc_extensions.py | 26 +++++++++++++++++++- docs/faq.rst | 7 +++--- docs/guides/feature-flags.rst | 46 +---------------------------------- 4 files changed, 31 insertions(+), 50 deletions(-) diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 1b093d3f696..828becf6a4f 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,4 +1,4 @@ [rstcheck] ignore_directives=automodule,http:get,tabs,tab -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..84238b1aef0 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,31 @@ 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.""" + features_dict = {} + for feature in Feature.FEATURES: + features_dict[feature[0].upper()] = feature[1].capitalize() + dl = nodes.definition_list() + for feature, desc in features_dict.items(): + term = nodes.term(text=feature) + definition = nodes.definition(text=desc) + dli = nodes.definition_list_item(term=term, definition=definition) + dl.append(dli) + return [dl], [] + + 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 3211777ecf0..2428f9e2431 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -65,11 +65,12 @@ environment, and will be set to ``True`` when building on RTD:: {% endif %} My project requires different settings than those available under Admin --------------------------------------------------------------------------- +----------------------------------------------------------------------- -Read the Docs offers additional flag settings. To enable these settings, +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 flag settings :doc:`here `. +Read more about these settings :doc:`here `. .. _github: https://github.com/rtfd/readthedocs.org diff --git a/docs/guides/feature-flags.rst b/docs/guides/feature-flags.rst index d0fdc41bd56..4d56260e8d8 100644 --- a/docs/guides/feature-flags.rst +++ b/docs/guides/feature-flags.rst @@ -12,48 +12,4 @@ or disable one or more of these featured flags for a particular project. Available Flags --------------- -USE_SPHINX_LATEST: -~~~~~~~~~~~~~~~~~~ - -Use latest version of Sphinx in building the project. - -USE_SETUPTOOLS_LATEST: -~~~~~~~~~~~~~~~~~~~~~~ - -Use latest version of setuptools in building the project. - -ALLOW_DEPRECATED_WEBHOOKS: -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Allow deprecated webhook views. - -PIP_ALWAYS_UPGRADE: -~~~~~~~~~~~~~~~~~~~ - -Always run: - -.. code-block:: bash - - pip install --upgrade - -before building the project. - -SKIP_SUBMODULES: -~~~~~~~~~~~~~~~~ - -Skip git submodule checkout. - -DONT_OVERWRITE_SPHINX_CONTEXT: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Do not overwrite context vars in conf.py with Read the Docs context. - -ALLOW_V2_CONFIG_FILE: -~~~~~~~~~~~~~~~~~~~~~ - -Allow to use the v2 of the configuration file. - -MKDOCS_THEME_RTD: -~~~~~~~~~~~~~~~~~ - -Use Read the Docs theme for MkDocs as default theme. +:featureflags: From 2f8cedbfe5137cd269e5bb15610e480ba454c6f6 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Fri, 4 Jan 2019 15:31:22 +0530 Subject: [PATCH 7/9] automatic updation of docsfor feature flags --- docs/doc_extensions.py | 11 ++++++----- docs/guides/feature-flags.rst | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index 84238b1aef0..d373f6d2224 100644 --- a/docs/doc_extensions.py +++ b/docs/doc_extensions.py @@ -29,12 +29,13 @@ def feature_flags_role(typ, rawtext, text, lineno, inliner, options=None, features_dict = {} for feature in Feature.FEATURES: features_dict[feature[0].upper()] = feature[1].capitalize() - dl = nodes.definition_list() + dli_list = [] for feature, desc in features_dict.items(): - term = nodes.term(text=feature) - definition = nodes.definition(text=desc) - dli = nodes.definition_list_item(term=term, definition=definition) - dl.append(dli) + term = nodes.term(text=nodes.Text(feature)) + definition = nodes.definition('', nodes.paragraph(text=desc)) + dli = nodes.definition_list_item('', term, definition) + dli_list.append(dli) + dl = nodes.definition_list('', *dli_list) return [dl], [] diff --git a/docs/guides/feature-flags.rst b/docs/guides/feature-flags.rst index 4d56260e8d8..38174e5e73e 100644 --- a/docs/guides/feature-flags.rst +++ b/docs/guides/feature-flags.rst @@ -12,4 +12,4 @@ or disable one or more of these featured flags for a particular project. Available Flags --------------- -:featureflags: +:featureflags:`TEMP` From 819e5c8434f80d2ced50056385c89d022f6cf908 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Fri, 18 Jan 2019 16:12:01 +0530 Subject: [PATCH 8/9] change working of role --- docs/doc_extensions.py | 17 ++++++----------- docs/guides/feature-flags.rst | 18 +++++++++++++++++- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index d373f6d2224..8e1055c6689 100644 --- a/docs/doc_extensions.py +++ b/docs/doc_extensions.py @@ -26,17 +26,12 @@ def django_setting_role(typ, rawtext, text, lineno, inliner, options=None, def feature_flags_role(typ, rawtext, text, lineno, inliner, options=None, content=None): """Up to date feature flags from the application.""" - features_dict = {} - for feature in Feature.FEATURES: - features_dict[feature[0].upper()] = feature[1].capitalize() - dli_list = [] - for feature, desc in features_dict.items(): - term = nodes.term(text=nodes.Text(feature)) - definition = nodes.definition('', nodes.paragraph(text=desc)) - dli = nodes.definition_list_item('', term, definition) - dli_list.append(dli) - dl = nodes.definition_list('', *dli_list) - return [dl], [] + all_features = Feature.FEATURES + requested_feature = utils.unescape(text) + for feature in all_features: + if text.lower() == feature[0].lower(): + desc = nodes.Text(feature[1], feature[1]) + return [desc], [] def setup(_): diff --git a/docs/guides/feature-flags.rst b/docs/guides/feature-flags.rst index 38174e5e73e..92600286b94 100644 --- a/docs/guides/feature-flags.rst +++ b/docs/guides/feature-flags.rst @@ -12,4 +12,20 @@ or disable one or more of these featured flags for a particular project. Available Flags --------------- -:featureflags:`TEMP` +``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` From 5d5c2ffa08e8aa483882584c11d180f21016f5f7 Mon Sep 17 00:00:00 2001 From: dojutsu-user Date: Fri, 18 Jan 2019 16:16:50 +0530 Subject: [PATCH 9/9] update if condition --- docs/doc_extensions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/doc_extensions.py b/docs/doc_extensions.py index 8e1055c6689..57b552abd73 100644 --- a/docs/doc_extensions.py +++ b/docs/doc_extensions.py @@ -29,7 +29,7 @@ def feature_flags_role(typ, rawtext, text, lineno, inliner, options=None, all_features = Feature.FEATURES requested_feature = utils.unescape(text) for feature in all_features: - if text.lower() == feature[0].lower(): + if requested_feature.lower() == feature[0].lower(): desc = nodes.Text(feature[1], feature[1]) return [desc], []