Skip to content
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

Docs for feature flag #5043

Merged
merged 10 commits into from
Jan 29, 2019
Merged

Docs for feature flag #5043

Show file tree
Hide file tree
Changes from 4 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
9 changes: 9 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,15 @@ environment, and will be set to ``True`` when building on RTD::
Woo
{% endif %}

My project requires different settings than that are available under Admin
dojutsu-user marked this conversation as resolved.
Show resolved Hide resolved
--------------------------------------------------------------------------
dojutsu-user marked this conversation as resolved.
Show resolved Hide resolved

Read the Docs offers additional flag settings. To enable these settings, please open an
dojutsu-user marked this conversation as resolved.
Show resolved Hide resolved
request issue on our `github`_ and we will change the settings for the project. Read more about
these flag 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
59 changes: 59 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,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
---------------
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:
~~~~~~~~~~~~~~~~~~

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.