Add a more generic deploy command and deprecate gh-deploy

[Andre601]

As per this comment does the gh-deploy command seem to be nothing more than a default mkdocs build -> Commit to branch gh-pages -> Push with the target branch being the only GitHub-specific thing.

I've mentioned it in the linked discussion, but repeat it here again for sake of being clear: I believe it would be a beneficial move to have the gh-deploy command be deprecated and instead add a more generic deploy command to use.
The main reason here is, that when people look at the command (And especially its description when running --help) do they get the impression that the command is only meant for GitHub and GitHub Pages when it could theoretically be used for any remote git repo host.

With a more generic command name, people would know that it can be used for hosts other than GitHub.

I personally would imagine the following command structure:

mkdocs deploy [OPTIONS] TARGET_BRANCH

TARGET_BRANCH would be required here. Reason is that with gh-deploy we can assume the default being gh-pages but with a more neutral command, this wouldn't be a good aproach as other repo hosts such as Codeberg have different branch names (In that example pages).

Tho maybe MkDocs could assume the branch to use based on the provided repo URL in the config (if any), but I feel like this would be kinda risky to do here...

[OPTIONS] could be one or multiple of these (Basically copied from gh-deploy help):

-c, --clean / --dirty       Remove old files from the site_dir before building (the default).
-m, --message TEXT          A commit message to use when commiting to the remote branch.
                            Commit {sha} and MkDocs {version} are available as expansions.
-r, --remote-name TEXT      The remote name to commit to. This overrides the value specified
                            in config
--force                     Force the push to the repository.
--no-history                Replace the whole Git history with one new commit.
--ignore-version            Ignore check that build is not being deployed with an older version
                            of MkDocs.
--shell                     Use the shell when invoking Git.
-f, --config-file FILENAME  Provide a specific MkDocs config. This can be a file name, or '-'
                            to read from stdin.
-s, --strict / --no-strict  Enable strict mode. This will cause MkDocs to abort the build on any
                            warnings.
-t, --theme [material|mkdocs|readthedocs]
                            The theme to use when building your documentation.
--use-directory-urls / --no-directory-urls
                            Use directory URLs when building pages (the default).
-d, --site-dir PATH         The directory to output the result of the documentation build.
-q, --quiet                 Silence warnings.
-v, --verbose               Enable verbose output.
-h, --help                  Show this message and exit.

One issue I can think of is a feature of MkDocs, which is displaying the URL your page is being deployed to, which I assume has some logic involved regarding CNAME file and github.io URL stuff, but I believe this option could be safely dropped as it usually doesn't have any main use outside of being informative.
Tho, if it should be included could perhaps the site_url within the config file be used to display. Or MkDocs could look for certain files (CNAME for GitHub, .domains for Codeberg as an example) to get the domain from...

---

Another alternative to the above suggestion I could see here is to deprecate the gh-deploy command and instead recommend and promote CI/CD setups to automatically publish your pages with.
I could think of two examples right now that could be shown in the docs:

• GitHub Actions setup
• Woodpecker-CI setup

Tho, I can see the benefit in having a deploy command for a quick and easy update of the site, so personally would I go with the first suggestion instead of the latter one.

[nielsnl68]

Hi, i like @Andre601's idea, i however i would love to have an option to set a different repo as well so i could have the documents in repo 1 and the site it self in repo 2.

Second thing is that i would have the settings in the mkdocs.yml like:

deployment:
    repo_url: https://github.com/esphome/esphome[.git] # the .git could be optional.
    repo_branch: gh-pages
    repo_username: ....
    repo_pw: !ENV git_password