Improve Configuration and Validation sections of the docs#989
Improve Configuration and Validation sections of the docs#989pedro-psb merged 5 commits intodynaconf:masterfrom
Conversation
✅ Deploy Preview for dynaconf ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Maybe I have to do absolute links (without the |
Codecov Report
@@ Coverage Diff @@
## master #989 +/- ##
=======================================
Coverage 98.70% 98.70%
=======================================
Files 23 23
Lines 2242 2242
=======================================
Hits 2213 2213
Misses 29 29 📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more |
pedro-psb
left a comment
There was a problem hiding this comment.
This is looking way better. I'm opinionated on some small things, but feel free to disagree if you have different motivations. And as I've said before, the grammar/type checker is better than me on catching typos, so I didn't bother with this too much.
| ) | ||
| ``` | ||
|
|
||
| <h4>Trigger manually</h4> |
There was a problem hiding this comment.
I think this information about keys is good, but it might be a best fit as first thing on the Usage section (along with some general info about a Validator object).
... (overview)
Usage
To define validation rules, you must create Validator objects, which are constructed using keys (positional arguments) and rules (kwargs):
Validator("AGE", gte=20, lte=80) # multiple rules
Validator("NAME", "VERSION", "PORT", must_exist=True) # multiple keys
Validator("DB.PORT", eq=8080) # keys with dot-path notationThere are some different ways to use them, as we'll see.
... (on instatiation)
There was a problem hiding this comment.
Done. What's the go-to section that explains that Dynaconf can handle weird keys? Like dotted lookups, the difference between upper and lower case, keys with __, and such? Maybe we should link it here.
There was a problem hiding this comment.
I'm not sure there if there is a single place where this is presented.
8a6a3ce to
22b0248
Compare
|
Thanks @pedro-psb for your input and patience. I pushed some changes, you can look at the diff here. Please don't hesitate to re-ask for changes, and please mark as solved any discussions you think should be closed. Edit: tried to fix the links. We'll see how that went. |
pedro-psb
left a comment
There was a problem hiding this comment.
I think this is good after the link fix. You can check if it works by running the mkdocs local server or in the Netlify comment (there is a link to a live preview of the PR).
docs/configuration.md
Outdated
|
|
||
| In practice, this forwards `validate_exclude` to the `exclude` kwarg during the validation step upon `Dynaconf` instantiation for all `Validator`s passed. Note that this setting has interaction with [`validate_only`](#validate_only). | ||
|
|
||
| Read more about it in the [selective validation](./validation#selective-validation) section. |
There was a problem hiding this comment.
This dot causes the link to resolve as configuration/validation#selective-validation, causing it to break.
We should have a link health checker in the dev tool chain.
docs/configuration.md
Outdated
|
|
||
| This setting only applies during `Dynaconf` instantiation. Further calls to `Dynaconf.validators.validate` will use the value passed to the `only` kwarg in that call. | ||
|
|
||
| In practice, this forwards `validate_only` to the `only` kwarg during the validation step upon `Dynaconf` instantiation for all `Validator`s passed. Note that this setting has interaction with [`validate_exclude`](#validate-exclude). |
There was a problem hiding this comment.
Here #validation-exclude should be #validation_exclude, because it uses _ explicitly. The link should use - when it comes from a whitespace transformation (e.g, if it was validation exclude).
docs/validation.md
Outdated
| no validation will be triggered. | ||
|
|
||
| You can override this globally with the option [validate_on_update](/configuration/#validate_on_update) or | ||
| You can override this globally with the option [validate_on_update](/configuration/#validate-on-update) or |
There was a problem hiding this comment.
Same here, the original uses literal underscores. I didn't see this detail about dash-underscore on my previous review.
|
Hey @pedro-psb, I'll look at your comments during the weekend. My bad with the links though, I could've sworn that I went through all of them :S. |
The guide specified Python 3.6+ when Dynaconf is 3.8+.
22b0248 to
7130a80
Compare
|
@pedro-psb sorry this is taking so long, I don't have much time mid-week to tackle this PR :S. I've now re-read and it looks like its better now. I'll look check all links from the dev deploy once it's ready. Edit: Links seem to work. Also caught some other formatting issues. Let me know what you think! Also: rebased with |
7130a80 to
5f1ae87
Compare
Rework structure as suggested by @pedro-psb in dynaconf#911, improve clarity in the text and expand on some subsections.
Add sections on validate_only_current_env, validate_only and validate_exclude.
5f1ae87 to
b5da6c2
Compare
pedro-psb
left a comment
There was a problem hiding this comment.
@sebastian-correa Don't need to apologize, I'm glad you took the effort to contribute!
It's good to go, we'll ship it in 3.2.4
Shortlog of commit since last release:
Bruno Rocha (2):
Release version 3.2.3
fix(env): allow underscore in env name dynaconf#1011 (dynaconf#1015)
Jake Callahan (1):
fix(vault): pin hvac minimum version
Pedro Pessoa (3):
fix(set): non-str key raising type error dynaconf#1005 (dynaconf#1008)
fix(merge): dynaconf_merge=False on nested structures (dynaconf#1012)
fix(cli): support for 'entrypoint-path' in FLASK_APP dynaconf#946 (dynaconf#1014)
Sebastian Correa (1):
doc(validation): Improve Configuration and Validation sections of the docs (dynaconf#989)
Vladislav Sharapov (1):
doc(envvars): Fix link to configuration page (dynaconf#1020)
Shortlog of commit since last release:
Bruno Rocha (2):
Release version 3.2.3
fix(env): allow underscore in env name dynaconf#1011 (dynaconf#1015)
Jake Callahan (1):
fix(vault): pin hvac minimum version
Pedro Pessoa (3):
fix(set): non-str key raising type error dynaconf#1005 (dynaconf#1008)
fix(merge): dynaconf_merge=False on nested structures (dynaconf#1012)
fix(cli): support for 'entrypoint-path' in FLASK_APP dynaconf#946 (dynaconf#1014)
Sebastian Correa (1):
doc(validation): Improve Configuration and Validation sections of the docs (dynaconf#989)
Vladislav Sharapov (1):
doc(envvars): Fix link to configuration page (dynaconf#1020)
Summary
Fixes #911 and #968 by adding documentation on some
Dynaconfparameters and reworking theValidationsection of the docs.Details
Not much detail to give, as context is present in the 2 linked issues.
Aside from the obvious additions to
configuration.mdandvalidation.md, I updated the Pyhon version inCONTRIBUTING.mdto 3.8+ and added.DS_Storefile to.gitignore. In particular, any of these 2 unrelated changes could be dropped from this PR if needed :).Questions
make docs). Did I do something wrong or do they get fixed when deployed to the web?Notes
Please feel free to ask any changes in this PR. The idea is to improve Dynaconf.