Docs for feature flag

[dojutsu-user]

Fixes #5041

[dojutsu-user]

I request to please suggest imorovements for english.

[RichardLitt]

Small language changes.

[stsewd]

Please follow our guidelines for contributing to documentation https://docs.readthedocs.io/en/latest/docs.html

[dojutsu-user]

@stsewd
Thank you.
I have pushed some changes and tried to follow the docs pointed by you.

[stsewd]

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

[dojutsu-user]

@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?

[stsewd]

List and description

[dojutsu-user]

@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:

[dojutsu-user]

@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

[agjohnson]

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.

[dojutsu-user]

@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

[agjohnson]

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.

[dojutsu-user]

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

[humitos]

Can you upload a screenshot so we can see how it will looks like? Thanks!

[dojutsu-user]

@humitos
Yes, of course.
Here is the link to the image.

But the look of it may change as per the comment by @agjohnson above.

[dojutsu-user]

I have pushed the changes.
Here is how the docs page looks

[ericholscher]

Looks good. 👍