Build settings docs from settings.json schema

[glennmatthews]

Closes #5099 (and progress toward #1150 as well)

What's Changed

• Add mkdocs-macros-plugin as a docs dependency
• Replace settings.json with settings.yaml as trying to represent Markdown-formatted text in JSON is a pain.
• Using this plugin, load settings.yaml into the rendering environment for the docs and use its contents to generate optional-settings.md and required-settings.md
  • Because we already have Django and Jinja templating text in the raw Markdown of other docs files, I configured the plugin's Jinja2 environment to use [[...]] and [[%...%]] instead of Jinja's default {{...}} and {%...%} tags so as to introduce the minimal number of unrelated changes to other docs files.
• Add new keys to settings.yaml to support more fully replicating the existing docs:
  • details - additional text beyond what's included in description, including hyperlinks to related reference material and so forth
  • default_literal - a string to render in the docs in cases where the given default isn't clear otherwise. Only used in 1 or 2 places at present.
  • environment_variable - the environment variable that can control this setting
  • version_added - the Nautobot version a setting was first added into
  • is_constance_setting - a boolean indicating that this setting is configurable via Constance.
  • is_required_setting - a boolean controlling whether this setting is documented in optional-settings or required-settings.
  • see_also - a dict of (link_text => link) entries for related documentation

The work is not complete at this time but I wanted to get this draft PR open to gather initial feedback and confirm that we want to continue down this road. In particular, I'm concerned that JSON's requirement to escape all newlines makes the details of many settings rather difficult to read in the JSON and presumably to maintain longer-term.

Screenshots

TODO

• Explanation of Change(s)
• Added change log fragment(s) (for more information see the documentation)
• Attached Screenshots, Payload Example
• Unit, Integration Tests
• Documentation Updates (when adding/changing features)
• Example Plugin Updates (when adding/changing features)
• Outline Remaining Work, Constraints from Design

[gsnider2195]

Can we find out if it's ok to change this to yaml?

[glennmatthews]

Can we find out if it's ok to change this to yaml?

I went ahead with doing so. I've asked the cloud folks for a 👍 but in the worst case if they absolutely need a json file, we can auto-generate one as a part of the docs build.

[glennmatthews]

• https://docs-landing-page--5363.org.readthedocs.build/projects/core/en/5363/user-guide/administration/configuration/required-settings/
• https://docs-landing-page--5363.org.readthedocs.build/projects/core/en/5363/user-guide/administration/configuration/optional-settings/

[gsnider2195]

Doesn't look like Django has ever supported this?

[glennmatthews]

Right, that's why I removed it. Sorry for not commenting on that fact.

[gsnider2195]

I noticed that we removed DISABLE_PREFIX_LIST_HIERARCHY because it's no longer a setting in 2.x but we didn't document this in any release notes, only in the upgrading from 1.x docs. I think we should have this in the 2.x release notes so it's more easily searchable.

[gsnider2195]

I noticed that we removed DISABLE_PREFIX_LIST_HIERARCHY because it's no longer a setting in 2.x but we didn't document this in any release notes, only in the upgrading from 1.x docs. I think we should have this in the 2.x release notes so it's more easily searchable.

Same for ENFORCE_GLOBAL_UNIQUE

[glennmatthews]

I noticed that we removed DISABLE_PREFIX_LIST_HIERARCHY because it's no longer a setting in 2.x but we didn't document this in any release notes, only in the upgrading from 1.x docs. I think we should have this in the 2.x release notes so it's more easily searchable.

Same for ENFORCE_GLOBAL_UNIQUE

Removal of ENFORCE_GLOBAL_UNIQUE is called out in the 2.0 release-notes "Release Overview". I'll add a note about DISABLE_PREFIX_LIST_HIERARCHY.

[glennmatthews]

FWIW, from a quick python check of the schema:

ADMINS lacks environment variable support
ALLOWED_URL_SCHEMES lacks environment variable support
CORS_ALLOWED_ORIGINS lacks environment variable support
CORS_ALLOWED_ORIGIN_REGEXES lacks environment variable support
CSRF_TRUSTED_ORIGINS lacks environment variable support
DATABASE_ROUTERS lacks environment variable support
EXEMPT_VIEW_PERMISSIONS lacks environment variable support
EXTERNAL_AUTH_DEFAULT_GROUPS lacks environment variable support
FORCE_SCRIPT_NAME lacks environment variable support
GRAPHQL_COMPUTED_FIELD_PREFIX lacks environment variable support
GRAPHQL_CUSTOM_FIELD_PREFIX lacks environment variable support
GRAPHQL_RELATIONSHIP_PREFIX lacks environment variable support
INTERNAL_IPS lacks environment variable support
MEDIA_ROOT lacks environment variable support
NAUTOBOT_ROOT lacks environment variable support
PLUGINS lacks environment variable support
SANITIZER_PATTERNS lacks environment variable support
SESSION_CACHE_ALIAS lacks environment variable support
SESSION_COOKIE_AGE lacks environment variable support
SESSION_ENGINE lacks environment variable support
STATIC_ROOT lacks environment variable support
STORAGE_BACKEND lacks environment variable support
UI_RACK_VIEW_TRUNCATE_FUNCTION lacks environment variable support

[glennmatthews]

I can't approve since I opened the PR, but looks good!