Skip to content

Docs for feature flag #5043

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Jan 29, 2019
Merged

Docs for feature flag #5043

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
3fbe47d
Add feature-flags page
dojutsu-user Dec 27, 2018
4adef9e
add ques on faq
dojutsu-user Dec 27, 2018
78389bb
Add the forgotten >
dojutsu-user Dec 28, 2018
c7c7370
fix relative link
dojutsu-user Dec 28, 2018
534026d
add improvements
dojutsu-user Jan 2, 2019
9bbd946
implement rst role
dojutsu-user Jan 3, 2019
2f8cedb
automatic updation of docsfor feature flags
dojutsu-user Jan 4, 2019
3e83667
Merge branch 'master' into docs-for-feature-flags
dojutsu-user Jan 11, 2019
819e5c8
change working of role
dojutsu-user Jan 18, 2019
5d5c2ff
update if condition
dojutsu-user Jan 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/.rstcheck.cfg
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
22 changes: 21 additions & 1 deletion docs/doc_extensions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -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',
Expand Down
10 changes: 10 additions & 0 deletions docs/faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------------------------------------------------

Expand Down
31 changes: 31 additions & 0 deletions docs/guides/feature-flags.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
---------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we could use a rst role to keep the list updated, something like #4451 (comment) https://github.com/rtfd/readthedocs.org/pull/4451/files#diff-d4de2c39f7f56cdad5a95921ae1398ec

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stsewd
I didn't get it.
Do you want to render the whole list (with description) with rst role? or just the description? or any other thing?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

List and description

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stsewd
I have tried it and i suppose that the function for "role" is working fine. However I am not able to get the output at the docs.
Can you please help me in this. I am unable to find the mistakes.
The output I'm getting is

featureflags:

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@stsewd
It was a wonderful idea. I managed to implement it successfully and now the flags with their description are rendering as desired automatically.
Here is the image of the feature flags docs page - image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I love adding features like this to our docs! 💯

I would suggest a change here: instead of using a role to put all of the different feature flags in a single block, this should mimic what the django setting role does.

Also, if you were to implement a feature like this normally, you'd use a directive, not a role. I do think role would be preferred here if you were to match how we are using the django setting role. It allows us to put more commentary around the output.

Copy link
Member Author

@dojutsu-user dojutsu-user Jan 11, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@agjohnson
I am a little confused.
This is what I'm getting now.

  • In the rst file, the use of the role should be like this. 
    ``FEATURE_1``: :featureflags:`FEATURE_1`
``FEATURE_2``: :featureflags:`FEATURE_2`
``FEATURE_3``: :featureflags:`FEATURE_3`
    which will render the feature flags with its description as nodes.Text.

But doing this, we will lost the automatic rendering of the docs.
Also, the docs will look like this - image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we want to fully automate things, there might be some feature flags we don't want documented or don't need documented.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the explanation.
I have followed your advice and changed the pattern of the role similar to djangosettings role.


``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`