[DOC] Add doc string to upgrade.py

[kcpevey]

Context

A file level documentation string summarizing how the upgrade sequence works would be highly beneficial.

Value and/or benefit

There are some doc strings on individual methods, but devs have to do quite a bit of reading and digging around the different methods included before they can understand how it all works. A high level doc string would go a long way in helping out.

Anything else?

No response

[arjxn-py]

Hi there, I can try working on this one upon confirmation.
Here's one sample docstring for do_upgrade method:

def do_upgrade(config_filename, attempt_fixes=False):
    """
    Perform an upgrade of the Nebari configuration file.

    This function loads the YAML configuration file, checks for deprecated keys,
    validates the current version, and if necessary, upgrades the configuration
    to the latest version of Nebari.

    Parameters:
    config_filename (str): The path to the configuration file.
    attempt_fixes (bool): Whether to attempt automatic fixes for validation errors.

    Returns:
    None
    """

Happy to have feedback on it. Thanks 💐

[Adam-D-Lewis]

Hi @arjxn-py, thanks for contributing! That doc string looks good and I'd be happy to merge a PR with that. Maybe also add something like the following at the top of the file.

"""This file contains the upgrade logic for Nebari.

This file contains the upgrade logic for Nebari.  Each release of Nebari requires an upgrade step class (which is a child class of UpgradeStep) to be created.  
When a user runs `nebari upgrade  -c nebari-config.yaml`, then the do_upgrade function will then run through all required upgrade steps to bring the config file up to date with the current version of Nebari.
"""

[Adam-D-Lewis]

Pinging @viniciusdc in case he has any thoughts here.

[arjxn-py]

Thanks so much for the input @Adam-D-Lewis 💐 , I'd be happy to open a PR soon with the docstrings along with the suggested one too.

[viniciusdc]

I just saw your PR @arjxn-py, fantastic work! thanks for the contribution.

[arjxn-py]

Thanks for the kind words @viniciusdc, will look forward to contribute more & add value :) 🚀