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.

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: autogenerate app config docs #5892

Merged
merged 10 commits into from
Mar 8, 2024
Merged

Conversation

psychedelicious
Copy link
Collaborator

What type of PR is this? (check all applicable)

  • Refactor
  • Feature
  • Bug Fix
  • Optimization
  • Documentation Update
  • Community Node Submission

Have you updated all relevant documentation?

  • Yes
  • No

Description

While iterating on MM2 configs, I wanted to update the docs. This proved very tedious and I discovered the configuration docs were terribly out of date.

This prompted me to automate updating the app config docs. The meat-n-potatoes are these changes:

docs: autogenerated app config docs

mkdocs can autogenerate python class docs from its docstrings. Our config is a pydantic model.

It's tedious and error-prone to duplicate docstrings from the pydantic field descriptions to the class docstrings.

  • Add helper function to generate a mkdocs-compatible docstring from the InvokeAIAppConfig class fields

scripts: add script to update config docstring

  • Add script to call config docstring helper function and write the docstring to the file directly
  • Add make target for this script

The docstrings for InvokeAIAppConfig now have a test that confirms they are current. If the test fails, you can run make update-config-docstring to update the docstrings.

The CONFIGURATION.md doc is updated to autogenerate docs for InvokeAIAppConfig. Much of the individual setting documentation is removed, but a few bits that give extra useful context are retained.

QA Instructions, Screenshots, Recordings

Run mkdocs serve and go to Features -> Configuration to see the docs.

Merge Plan

This PR can be merged when approved

@github-actions github-actions bot added python PRs that change python files Root services PRs that change app services python-tests PRs that change python tests docs PRs that change docs labels Mar 8, 2024
psychedelicious and others added 10 commits March 8, 2024 15:36
It's not clear why these are still in the config class.
mkdocs can autogenerate python class docs from its docstrings. Our config is a pydantic model.

It's tedious and error-prone to duplicate docstrings from the pydantic field descriptions to the class docstrings.

- Add helper function to generate a mkdocs-compatible docstring from the InvokeAIAppConfig class fields
- Add script to call config docstring helper function and write the docstring to the file directly
- Add `make` target for this script
The tests were testing deprecated settings (not the settings themselves, just the class's functionality).
@brandonrising brandonrising enabled auto-merge (rebase) March 8, 2024 21:29
@brandonrising brandonrising merged commit 0bd9a0a into main Mar 8, 2024
14 checks passed
@brandonrising brandonrising deleted the psyche/docs/config-docstrings branch March 8, 2024 21:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs PRs that change docs python PRs that change python files python-tests PRs that change python tests Root services PRs that change app services
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants