From 205f57419e175b78e19cb647e9e8bcdc28a315e3 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Mon, 24 Oct 2022 12:27:31 -0500 Subject: [PATCH 01/28] generate api docs --- docs/.gitignore | 3 + docs/api_docs/README.md | 30 +++++++++ docs/api_docs/api_doc_mods.py | 117 ++++++++++++++++++++++++++++++++++ docs/api_docs/build.novella | 7 ++ setup.cfg | 3 + 5 files changed, 160 insertions(+) create mode 100644 docs/api_docs/README.md create mode 100644 docs/api_docs/api_doc_mods.py create mode 100644 docs/api_docs/build.novella diff --git a/docs/.gitignore b/docs/.gitignore index 565e21266..c334ed175 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -70,3 +70,6 @@ yarn-error.log* app/__pycache__ docs/users.pdf + +# docs +docs/api_docs/api_temp.md diff --git a/docs/api_docs/README.md b/docs/api_docs/README.md new file mode 100644 index 000000000..8344298d0 --- /dev/null +++ b/docs/api_docs/README.md @@ -0,0 +1,30 @@ +# Nebari API docs + +The Nebari API docs are generated from this repo, then merged into the nebari-docs repo via PR opened by GitHub Actions. + +## Environment + + +```bash +pip install -e ".[docs]" +``` + +## Workflow + +The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI. + +```bash + +git clone git@github.com:nebari-dev/nebari-docs.git +cd nebari-docs/docs/ + +cd docs/api_docs/ + +pydoc-markdown -I "../../" -p qhub --render-toc > api_temp.md + +python api_doc_mods.py --autogen_path api_temp.md --outpath ../../nebari-docs/docs/docs/references/api_docs.md + +cd ../../nebari-docs/docs/docs/references + +git diff api_docs.md +``` diff --git a/docs/api_docs/api_doc_mods.py b/docs/api_docs/api_doc_mods.py new file mode 100644 index 000000000..e26861157 --- /dev/null +++ b/docs/api_docs/api_doc_mods.py @@ -0,0 +1,117 @@ +from copy import deepcopy +from pathlib import Path + +import click + + +def insert_lines(source_list: list, idx: int, lines: list) -> None: + """Inject a list of lines at a given index""" + lines_r = deepcopy(lines) + lines_r.reverse() + [source_list.insert(idx, line) for line in lines_r] + + +def modify_autogen_api_docs(autogen_path: Path, outpath: Path) -> None: + """Modifications to the auto-generated API docs in order to make them + presentable. + + Args: + autogen_path (Path): path to the autogenerated API docs (*.md) + outpath (Path): output path for the modified docs (*.md) + """ + if not isinstance(autogen_path, Path): + autogen_path = Path(autogen_path) + + if not isinstance(outpath, Path): + outpath = Path(outpath) + + with open(autogen_path) as f: + text = f.readlines() + + header_info = [ + "---\n", + "title: API Documentation\n", + "description: Reference to API docs\n", + "---\n", + "# API Documentation\n", + "## Table of Contents\n", + ] + + # remove Table of contents header + del text[0] + + # insert new header + insert_lines(text, 0, header_info) + + # fix header flags (otherwise page nav won't work) + for idx, line in enumerate(text): + if line[0:7] == "# qhub.": + text[idx] = "##" + line + elif line == "# qhub\n": + text[idx] = "## qhub\n" + + keep_docs = [ + '"qhub.initialize', + '"qhub.cli.deploy', + '"qhub.cli.destroy', + '"qhub.cli.initialize', + '"qhub.cli.render', + '"qhub.cli.support', + '"qhub.cli', + '"qhub.cli.upgrade', + '"qhub.cli.validate', + '"qhub.render', + '"qhub.destroy', + ] + + id_idx = [] + keep_idx = [] + for idx, line in enumerate(text): + if line.startswith(" Date: Tue, 25 Oct 2022 12:25:39 -0500 Subject: [PATCH 02/28] add api docs here, add workflow --- .github/workflows/update_api_docs.yml | 84 ++++ docs/api_docs/api_doc.md | 561 ++++++++++++++++++++++++++ docs/api_docs/api_doc_mods.py | 1 + 3 files changed, 646 insertions(+) create mode 100644 .github/workflows/update_api_docs.yml create mode 100644 docs/api_docs/api_doc.md diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml new file mode 100644 index 000000000..b65789a9c --- /dev/null +++ b/.github/workflows/update_api_docs.yml @@ -0,0 +1,84 @@ +name: Update API docs + +on: + pull_request: + push: + branches: + - main + workflow_dispatch: + +jobs: + update_api: + runs-on: ubuntu-latest + defaults: + run: + shell: bash -l {0} + working-directory: ./docs/api_docs + steps: + - name: Check out repository 🛎️ + uses: actions/checkout@v3 + + - name: Install conda dependencies + uses: conda-incubator/setup-miniconda@v2 + with: + python-version: "3.10" + activate-environment: qhub-dev + environment-file: environment-dev.yaml + auto-activate-base: true + + - name: Install nebari and docs dependencies + run: pip install -e ".[docs]" + + - name: Conda list + run: conda list + + - name: Look for changes to cli files + uses: tj-actions/verify-changed-files@v12 + id: verify-changed-files + with: + files: | + qhub/cli/* + + - name: Run step only when files change. + if: steps.verify-changed-files.outputs.files_changed == 'true' + run: | + echo "Changed files: ${{ steps.verify-changed-files.outputs.changed_files }}" + # Outputs: "Changed files: new.txt test_directory/new.txt" + + - name: Generate new API docs + run: | + # cd docs/api_docs/ + # generate the new docs + pydoc-markdown -I "../../" -p qhub --render-toc > api_temp.md + # make modifications to clean up + python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md + + - name: Check for changes + run: | + if git diff --exit-code; then + echo "::set-env name=changes_exist::true" + else + echo "::set-env name=changes_exist::false" + fi + + - name: Create Pull Request in code repo + id: cpr + uses: peter-evans/create-pull-request@v4 + if: ${{ env.changes_exist == 'true' }} + with: + token: ${{ secrets.NEBARI_SENSEI_API_DOCS_PR_OPENER }} + commit-message: Update report + committer: GitHub + author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com> + signoff: false + branch: auto_api_doc_update + delete-branch: true + title: '[AUTO] Update API doc' + body: | + Update API doc + - Auto-generated by [create-pull-request][1] + + [1]: https://github.com/peter-evans/create-pull-request + labels: | + "area: documentation 📖" + draft: false diff --git a/docs/api_docs/api_doc.md b/docs/api_docs/api_doc.md new file mode 100644 index 000000000..aef5e1764 --- /dev/null +++ b/docs/api_docs/api_doc.md @@ -0,0 +1,561 @@ +--- +title: API Documentation +description: Reference to API docs +--- +<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation +## Table of Contents + + + + +### qhub.destroy + + + +### qhub.initialize + + + +### qhub.render + + + +#### render\_contents + +```python +def render_contents(config: Dict) +``` + +Dynamically generated contents from QHub configuration + + + +#### gen\_gitignore + +```python +def gen_gitignore(config) +``` + +Generate `.gitignore` file. +Add files as needed. + + + +#### gen\_cicd + +```python +def gen_cicd(config) +``` + +Use cicd schema to generate workflow files based on the +`ci_cd` key in the `config`. + +For more detail on schema: +GiHub-Actions - qhub/providers/cicd/github.py +GitLab-CI - qhub/providers/cicd/gitlab.py + + + +#### inspect\_files + +```python +def inspect_files(source_dirs: str, + output_dirs: str, + source_base_dir: str, + output_base_dir: str, + ignore_filenames: List[str] = None, + ignore_directories: List[str] = None, + deleted_paths: List[str] = None, + contents: Dict[str, str] = None) +``` + +Return created, updated and untracked files by computing a checksum over the provided directory + +**Arguments**: + +- `source_dirs` _str_ - The source dir used as base for comparssion +- `output_dirs` _str_ - The destination dir which will be matched with +- `source_base_dir` _str_ - Relative base path to source directory +- `output_base_dir` _str_ - Relative base path to output directory +- `ignore_filenames` _list[str]_ - Filenames to ignore while comparing for changes +- `ignore_directories` _list[str]_ - Directories to ignore while comparing for changes +- `deleted_paths` _list[str]_ - Paths that if exist in output directory should be deleted +- `contents` _dict_ - filename to content mapping for dynamically generated files + + + +#### hash\_file + +```python +def hash_file(file_path: str) +``` + +Get the hex digest of the given file + +**Arguments**: + +- `file_path` _str_ - path to file + + + +#### set\_env\_vars\_in\_config + +```python +def set_env_vars_in_config(config) +``` + +For values in the config starting with 'QHUB_SECRET_XXX' the environment +variables are searched for the pattern XXX and the config value is +modified. This enables setting secret values that should not be directly +stored in the config file. + +NOTE: variables are most likely written to a file somewhere upon render. In +order to further reduce risk of exposure of any of these variables you might +consider preventing storage of the terraform render output. + + + +### qhub.cli.support + + + +### qhub.cli.deploy + + + +### qhub.cli.\_init + + + +#### handle\_init + +```python +def handle_init(inputs: InitInputs) +``` + +Take the inputs from the `nebari init` command, render the config and write it to a local yaml file. + + + +#### check\_cloud\_provider\_creds + +```python +def check_cloud_provider_creds(ctx: typer.Context, cloud_provider: str) +``` + +Validate that the necessary cloud credentials have been set as environment variables. + + + +#### check\_auth\_provider\_creds + +```python +def check_auth_provider_creds(ctx: typer.Context, auth_provider: str) +``` + +Validating the the necessary auth provider credentials have been set as environment variables. + + + +#### check\_project\_name + +```python +def check_project_name(ctx: typer.Context, project_name: str) +``` + +Validate the project_name is acceptable. Depends on `cloud_provider`. + + + +#### guided\_init\_wizard + +```python +def guided_init_wizard(ctx: typer.Context, guided_init: str) +``` + +Guided Init Wizard is a user-friendly questionnaire used to help generate the `nebari-config.yaml`. + + + +### qhub.cli.destroy + + + +### qhub.cli.initialize + + + +### qhub.cli.render + + + +### qhub.cli + + + +### qhub.cli.upgrade + + + +### qhub.cli.validate + + + +### qhub.cli.\_keycloak + + + +#### add\_user + +```python +@app_keycloak.command(name="adduser") +def add_user(add_users: Tuple[str, str] = typer.Option( + ..., "--user", help="Provide both: "), + config_filename: str = typer.Option( + ..., + "-c", + "--config", + help="qhub configuration file path", + )) +``` + +Add a user to Keycloak. User will be automatically added to the [italic]analyst[/italic] group. + + + +#### list\_users + +```python +@app_keycloak.command(name="listusers") +def list_users(config_filename: str = typer.Option( + ..., + "-c", + "--config", + help="qhub configuration file path", +)) +``` + +List the users in Keycloak. + + + +### qhub.cli.keycloak + + + +### qhub.cli.cost + + + +### qhub.cli.main + + + +## OrderCommands Objects + +```python +class OrderCommands(TyperGroup) +``` + + + +#### list\_commands + +```python +def list_commands(ctx: Context) +``` + +Return list of commands in the order appear. + + + +#### init + +```python +@app.command() +def init(cloud_provider: str = typer.Argument( + "local", + help=f"options: {enum_to_list(ProviderEnum)}", + callback=check_cloud_provider_creds, + is_eager=True, +), + guided_init: bool = typer.Option( + False, + help=GUIDED_INIT_MSG, + callback=guided_init_wizard, + is_eager=True, + ), + project_name: str = typer.Option( + ..., + "--project-name", + "--project", + "-p", + callback=check_project_name, + ), + domain_name: str = typer.Option( + ..., + "--domain-name", + "--domain", + "-d", + ), + namespace: str = typer.Option("dev", ), + auth_provider: str = typer.Option( + "password", + help=f"options: {enum_to_list(AuthenticationEnum)}", + callback=check_auth_provider_creds, + ), + auth_auto_provision: bool = typer.Option(False, ), + repository: str = typer.Option(None, ), + repository_auto_provision: bool = typer.Option(False, ), + ci_provider: str = typer.Option( + None, + help=f"options: {enum_to_list(CiEnum)}", + ), + terraform_state: str = typer.Option( + "remote", help=f"options: {enum_to_list(TerraformStateEnum)}"), + kubernetes_version: str = typer.Option("latest", ), + ssl_cert_email: str = typer.Option(None, ), + disable_prompt: bool = typer.Option( + False, + is_eager=True, + )) +``` + +Create and initialize your [purple]nebari-config.yaml[/purple] file. + +This command will create and initialize your [purple]nebari-config.yaml[/purple] :sparkles: + +This file contains all your Nebari cluster configuration details and, +is used as input to later commands such as [green]nebari render[/green], [green]nebari deploy[/green], etc. + +If you're new to Nebari, we recommend you use the Guided Init wizard. +To get started simply run: + + [green]nebari init --guided-init[/green] + + + +#### validate + +```python +@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) +def validate(config: str = typer.Option( + ..., + "--config", + "-c", + help= + "qhub configuration yaml file path, please pass in as -c/--config flag", +), + enable_commenting: bool = typer.Option( + False, + "--enable_commenting", + help="Toggle PR commenting on GitHub Actions")) +``` + +Validate the values in the [purple]nebari-config.yaml[/purple] file are acceptable. + + + +#### render + +```python +@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) +def render( + output: str = typer.Option( + "./", + "-o", + "--output", + help="output directory", + ), + config: str = typer.Option( + ..., + "-c", + "--config", + help="nebari configuration yaml file path", + ), + dry_run: bool = typer. + Option( + False, + "--dry-run", + help= + "simulate rendering files without actually writing or updating any files", + )) +``` + +Dynamically render the Terraform scripts and other files from your [purple]nebari-config.yaml[/purple] file. + + + +#### deploy + +```python +@app.command() +def deploy( + config: str = typer.Option( + ..., + "--config", + "-c", + help="nebari configuration yaml file path", + ), + output: str = typer.Option( + "./", + "-o", + "--output", + help="output directory", + ), + dns_provider: str = typer.Option( + False, + "--dns-provider", + help="dns provider to use for registering domain name mapping", + ), + dns_auto_provision: bool = typer. + Option( + False, + "--dns-auto-provision", + help= + "Attempt to automatically provision DNS. For Auth0 is requires environment variables AUTH0_DOMAIN, AUTH0_CLIENTID, AUTH0_CLIENT_SECRET", + ), + disable_prompt: bool = typer.Option( + False, + "--disable-prompt", + help="Disable human intervention", + ), + disable_render: bool = typer.Option( + False, + "--disable-render", + help="Disable auto-rendering in deploy stage", + )) +``` + +Deploy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. + + + +#### destroy + +```python +@app.command() +def destroy( + config: str = typer.Option(..., + "-c", + "--config", + help="qhub configuration file path"), + output: str = typer.Option( + "./" + "-o", + "--output", + help="output directory", + ), + disable_render: bool = typer.Option( + False, + "--disable-render", + help="Disable auto-rendering before destroy", + ), + disable_prompt: bool = typer. + Option( + False, + "--disable-prompt", + help= + "Destroy entire Nebari cluster without confirmation request. Suggested for CI use.", + )) +``` + +Destroy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. + + + +#### cost + +```python +@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) +def cost(path: str = typer.Option( + None, + "-p", + "--path", + help= + "Pass the path of your stages directory generated after rendering QHub configurations before deployment", +), + dashboard: bool = typer.Option( + True, + "-d", + "--dashboard", + help="Enable the cost dashboard", + ), + file: str = typer.Option( + None, + "-f", + "--file", + help="Specify the path of the file to store the cost report", + ), + currency: str = typer.Option( + "USD", + "-c", + "--currency", + help="Specify the currency code to use in the cost report", + ), + compare: bool = typer.Option( + False, + "-cc", + "--compare", + help="Compare the cost report to a previously generated report", + )) +``` + +Estimate the cost of deploying Nebari based on your [purple]nebari-config.yaml[/purple]. [italic]Experimental.[/italic] + +[italic]This is still only experimental using Infracost under the hood. +The estimated value is a base cost and does not include usage costs.[/italic] + + + +#### upgrade + +```python +@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) +def upgrade( + config: str = typer.Option( + ..., + "-c", + "--config", + help="qhub configuration file path", + ), + attempt_fixes: bool = typer. + Option( + False, + "--attempt-fixes", + help= + "Attempt to fix the config for any incompatibilities between your old and new QHub versions.", + )) +``` + +Upgrade your [purple]nebari-config.yaml[/purple] from pre-0.4.0 to 0.4.0. + +Due to several breaking changes that came with the 0.4.0 release, this utility is available to help +update your [purple]nebari-config.yaml[/purple] to comply with the introduced changes. +See the project [green]RELEASE.md[/green] for details. + + + +#### support + +```python +@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) +def support(config_filename: str = typer.Option( + ..., + "-c", + "--config", + help="qhub configuration file path", +), + output: str = typer.Option( + "./qhub-support-logs.zip", + "-o", + "--output", + help="output filename", + )) +``` + +Support tool to write all Kubernetes logs locally and compress them into a zip file. + +The Nebari team recommends k9s to manage and inspect the state of the cluster. +However, this command occasionally helpful for debugging purposes should the logs need to be shared. + diff --git a/docs/api_docs/api_doc_mods.py b/docs/api_docs/api_doc_mods.py index e26861157..dc2690d67 100644 --- a/docs/api_docs/api_doc_mods.py +++ b/docs/api_docs/api_doc_mods.py @@ -33,6 +33,7 @@ def modify_autogen_api_docs(autogen_path: Path, outpath: Path) -> None: "title: API Documentation\n", "description: Reference to API docs\n", "---\n", + "<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED --->", "# API Documentation\n", "## Table of Contents\n", ] From 4f908c889cad85351abc8989d97172b1abce383d Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Tue, 25 Oct 2022 12:26:39 -0500 Subject: [PATCH 03/28] add temp file --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 9e1861986..2c7576a20 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ # docs .nox _build +docs/api_docs/api_temp.md # setuptools scm qhub/_version.py From 615c41a727e0ac6477e736648a43ca992f9260fe Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Tue, 25 Oct 2022 12:36:22 -0500 Subject: [PATCH 04/28] linting --- .github/workflows/update_api_docs.yml | 2 +- docs/api_docs/README.md | 12 +-- docs/api_docs/api_doc.md | 108 ++++++++++++-------------- docs/api_docs/build.novella | 2 +- 4 files changed, 54 insertions(+), 70 deletions(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index b65789a9c..952d08db8 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -51,7 +51,7 @@ jobs: # generate the new docs pydoc-markdown -I "../../" -p qhub --render-toc > api_temp.md # make modifications to clean up - python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md + python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md - name: Check for changes run: | diff --git a/docs/api_docs/README.md b/docs/api_docs/README.md index 8344298d0..a8e591986 100644 --- a/docs/api_docs/README.md +++ b/docs/api_docs/README.md @@ -1,30 +1,24 @@ # Nebari API docs -The Nebari API docs are generated from this repo, then merged into the nebari-docs repo via PR opened by GitHub Actions. +The Nebari API docs are generated from this repo, then merged into the nebari-docs repo via PR opened by GitHub Actions. ## Environment - ```bash pip install -e ".[docs]" ``` ## Workflow -The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI. +The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI. ```bash -git clone git@github.com:nebari-dev/nebari-docs.git -cd nebari-docs/docs/ +git clone git@github.com:nebari-dev/nebari-docs.git cd docs/api_docs/ pydoc-markdown -I "../../" -p qhub --render-toc > api_temp.md python api_doc_mods.py --autogen_path api_temp.md --outpath ../../nebari-docs/docs/docs/references/api_docs.md - -cd ../../nebari-docs/docs/docs/references - -git diff api_docs.md ``` diff --git a/docs/api_docs/api_doc.md b/docs/api_docs/api_doc.md index aef5e1764..53a3a8e08 100644 --- a/docs/api_docs/api_doc.md +++ b/docs/api_docs/api_doc.md @@ -1,10 +1,10 @@ ---- -title: API Documentation -description: Reference to API docs ---- -<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation -## Table of Contents +______________________________________________________________________ + +## title: API Documentation description: Reference to API docs +\<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation + +## Table of Contents @@ -20,7 +20,7 @@ description: Reference to API docs -#### render\_contents +#### render_contents ```python def render_contents(config: Dict) @@ -30,33 +30,29 @@ Dynamically generated contents from QHub configuration -#### gen\_gitignore +#### gen_gitignore ```python def gen_gitignore(config) ``` -Generate `.gitignore` file. -Add files as needed. +Generate `.gitignore` file. Add files as needed. -#### gen\_cicd +#### gen_cicd ```python def gen_cicd(config) ``` -Use cicd schema to generate workflow files based on the -`ci_cd` key in the `config`. +Use cicd schema to generate workflow files based on the `ci_cd` key in the `config`. -For more detail on schema: -GiHub-Actions - qhub/providers/cicd/github.py -GitLab-CI - qhub/providers/cicd/gitlab.py +For more detail on schema: GiHub-Actions - qhub/providers/cicd/github.py GitLab-CI - qhub/providers/cicd/gitlab.py -#### inspect\_files +#### inspect_files ```python def inspect_files(source_dirs: str, @@ -77,14 +73,14 @@ Return created, updated and untracked files by computing a checksum over the pro - `output_dirs` _str_ - The destination dir which will be matched with - `source_base_dir` _str_ - Relative base path to source directory - `output_base_dir` _str_ - Relative base path to output directory -- `ignore_filenames` _list[str]_ - Filenames to ignore while comparing for changes -- `ignore_directories` _list[str]_ - Directories to ignore while comparing for changes -- `deleted_paths` _list[str]_ - Paths that if exist in output directory should be deleted +- `ignore_filenames` _list\[str\]_ - Filenames to ignore while comparing for changes +- `ignore_directories` _list\[str\]_ - Directories to ignore while comparing for changes +- `deleted_paths` _list\[str\]_ - Paths that if exist in output directory should be deleted - `contents` _dict_ - filename to content mapping for dynamically generated files -#### hash\_file +#### hash_file ```python def hash_file(file_path: str) @@ -98,20 +94,17 @@ Get the hex digest of the given file -#### set\_env\_vars\_in\_config +#### set_env_vars_in_config ```python def set_env_vars_in_config(config) ``` -For values in the config starting with 'QHUB_SECRET_XXX' the environment -variables are searched for the pattern XXX and the config value is -modified. This enables setting secret values that should not be directly -stored in the config file. +For values in the config starting with 'QHUB_SECRET_XXX' the environment variables are searched for the pattern XXX and the config value is modified. This enables setting secret +values that should not be directly stored in the config file. -NOTE: variables are most likely written to a file somewhere upon render. In -order to further reduce risk of exposure of any of these variables you might -consider preventing storage of the terraform render output. +NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of any of these variables you might consider preventing storage +of the terraform render output. @@ -127,7 +120,7 @@ consider preventing storage of the terraform render output. -#### handle\_init +#### handle_init ```python def handle_init(inputs: InitInputs) @@ -137,7 +130,7 @@ Take the inputs from the `nebari init` command, render the config and write it t -#### check\_cloud\_provider\_creds +#### check_cloud_provider_creds ```python def check_cloud_provider_creds(ctx: typer.Context, cloud_provider: str) @@ -147,7 +140,7 @@ Validate that the necessary cloud credentials have been set as environment varia -#### check\_auth\_provider\_creds +#### check_auth_provider_creds ```python def check_auth_provider_creds(ctx: typer.Context, auth_provider: str) @@ -157,7 +150,7 @@ Validating the the necessary auth provider credentials have been set as environm -#### check\_project\_name +#### check_project_name ```python def check_project_name(ctx: typer.Context, project_name: str) @@ -167,7 +160,7 @@ Validate the project_name is acceptable. Depends on `cloud_provider`. -#### guided\_init\_wizard +#### guided_init_wizard ```python def guided_init_wizard(ctx: typer.Context, guided_init: str) @@ -205,7 +198,7 @@ Guided Init Wizard is a user-friendly questionnaire used to help generate the `n -#### add\_user +#### add_user ```python @app_keycloak.command(name="adduser") @@ -219,11 +212,11 @@ def add_user(add_users: Tuple[str, str] = typer.Option( )) ``` -Add a user to Keycloak. User will be automatically added to the [italic]analyst[/italic] group. +Add a user to Keycloak. User will be automatically added to the \[italic\]analyst\[/italic\] group. -#### list\_users +#### list_users ```python @app_keycloak.command(name="listusers") @@ -259,7 +252,7 @@ class OrderCommands(TyperGroup) -#### list\_commands +#### list_commands ```python def list_commands(ctx: Context) @@ -321,17 +314,18 @@ def init(cloud_provider: str = typer.Argument( )) ``` -Create and initialize your [purple]nebari-config.yaml[/purple] file. +Create and initialize your \[purple\]nebari-config.yaml\[/purple\] file. -This command will create and initialize your [purple]nebari-config.yaml[/purple] :sparkles: +This command will create and initialize your \[purple\]nebari-config.yaml\[/purple\] :sparkles: -This file contains all your Nebari cluster configuration details and, -is used as input to later commands such as [green]nebari render[/green], [green]nebari deploy[/green], etc. +This file contains all your Nebari cluster configuration details and, is used as input to later commands such as \[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], +etc. -If you're new to Nebari, we recommend you use the Guided Init wizard. -To get started simply run: +If you're new to Nebari, we recommend you use the Guided Init wizard. To get started simply run: - [green]nebari init --guided-init[/green] +``` + [green]nebari init --guided-init[/green] +``` @@ -352,7 +346,7 @@ def validate(config: str = typer.Option( help="Toggle PR commenting on GitHub Actions")) ``` -Validate the values in the [purple]nebari-config.yaml[/purple] file are acceptable. +Validate the values in the \[purple\]nebari-config.yaml\[/purple\] file are acceptable. @@ -382,7 +376,7 @@ def render( )) ``` -Dynamically render the Terraform scripts and other files from your [purple]nebari-config.yaml[/purple] file. +Dynamically render the Terraform scripts and other files from your \[purple\]nebari-config.yaml\[/purple\] file. @@ -427,7 +421,7 @@ def deploy( )) ``` -Deploy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. +Deploy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. @@ -460,7 +454,7 @@ def destroy( )) ``` -Destroy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. +Destroy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. @@ -501,10 +495,9 @@ def cost(path: str = typer.Option( )) ``` -Estimate the cost of deploying Nebari based on your [purple]nebari-config.yaml[/purple]. [italic]Experimental.[/italic] +Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. \[italic\]Experimental.\[/italic\] -[italic]This is still only experimental using Infracost under the hood. -The estimated value is a base cost and does not include usage costs.[/italic] +\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does not include usage costs.\[/italic\] @@ -528,11 +521,10 @@ def upgrade( )) ``` -Upgrade your [purple]nebari-config.yaml[/purple] from pre-0.4.0 to 0.4.0. +Upgrade your \[purple\]nebari-config.yaml\[/purple\] from pre-0.4.0 to 0.4.0. -Due to several breaking changes that came with the 0.4.0 release, this utility is available to help -update your [purple]nebari-config.yaml[/purple] to comply with the introduced changes. -See the project [green]RELEASE.md[/green] for details. +Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your \[purple\]nebari-config.yaml\[/purple\] to comply with the +introduced changes. See the project \[green\]RELEASE.md\[/green\] for details. @@ -556,6 +548,4 @@ def support(config_filename: str = typer.Option( Support tool to write all Kubernetes logs locally and compress them into a zip file. -The Nebari team recommends k9s to manage and inspect the state of the cluster. -However, this command occasionally helpful for debugging purposes should the logs need to be shared. - +The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally helpful for debugging purposes should the logs need to be shared. diff --git a/docs/api_docs/build.novella b/docs/api_docs/build.novella index 52f4e27d0..bb96f1a7d 100644 --- a/docs/api_docs/build.novella +++ b/docs/api_docs/build.novella @@ -4,4 +4,4 @@ template "docusaurus" { action "preprocess-markdown" { use "pydoc" -} \ No newline at end of file +} From 7390150f9d6fd7b956278a7eb6c81f865b34d3b2 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Wed, 14 Dec 2022 12:54:57 -0600 Subject: [PATCH 05/28] updates for nebari rename and other minor fixes --- .github/workflows/update_api_docs.yml | 16 +++++++--------- docs/api_docs/README.md | 17 ++++++++++++----- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index 952d08db8..2dc10b125 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -22,12 +22,12 @@ jobs: uses: conda-incubator/setup-miniconda@v2 with: python-version: "3.10" - activate-environment: qhub-dev + activate-environment: nebari-dev environment-file: environment-dev.yaml auto-activate-base: true - name: Install nebari and docs dependencies - run: pip install -e ".[docs]" + run: pip install -e "../..[docs]" - name: Conda list run: conda list @@ -37,20 +37,18 @@ jobs: id: verify-changed-files with: files: | - qhub/cli/* + nebari/cli/* - - name: Run step only when files change. + - name: Look for file changes if: steps.verify-changed-files.outputs.files_changed == 'true' run: | echo "Changed files: ${{ steps.verify-changed-files.outputs.changed_files }}" - # Outputs: "Changed files: new.txt test_directory/new.txt" - name: Generate new API docs run: | - # cd docs/api_docs/ - # generate the new docs - pydoc-markdown -I "../../" -p qhub --render-toc > api_temp.md - # make modifications to clean up + echo "generate the new docs" + pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md + echo "make modifications to clean up" python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md - name: Check for changes diff --git a/docs/api_docs/README.md b/docs/api_docs/README.md index a8e591986..718abc793 100644 --- a/docs/api_docs/README.md +++ b/docs/api_docs/README.md @@ -4,6 +4,8 @@ The Nebari API docs are generated from this repo, then merged into the nebari-do ## Environment +From the root of the repo: + ```bash pip install -e ".[docs]" ``` @@ -12,13 +14,18 @@ pip install -e ".[docs]" The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI. -```bash +The workflow described below will create the API docs. A formatting script is used to do a bit of cleanup and then +copy the resulting file over to the local docs repo. +```bash +# clone the docs repo git clone git@github.com:nebari-dev/nebari-docs.git - +# work out of the api_docs directory in the nebari repo cd docs/api_docs/ - -pydoc-markdown -I "../../" -p qhub --render-toc > api_temp.md - +# auto generate the api docs +pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md +# make formatting modifications and copy into the docs repo python api_doc_mods.py --autogen_path api_temp.md --outpath ../../nebari-docs/docs/docs/references/api_docs.md ``` + +Now you are ready to open up a PR with these changes. \ No newline at end of file From aed5eade13e742e6a94e6d16b0b269fb122756a7 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 14 Dec 2022 18:55:13 +0000 Subject: [PATCH 06/28] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/api_docs/README.md | 6 +++--- docs/api_docs/api_doc.md | 26 +++++++++++++++----------- 2 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/api_docs/README.md b/docs/api_docs/README.md index 718abc793..c3c314a04 100644 --- a/docs/api_docs/README.md +++ b/docs/api_docs/README.md @@ -14,8 +14,8 @@ pip install -e ".[docs]" The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI. -The workflow described below will create the API docs. A formatting script is used to do a bit of cleanup and then -copy the resulting file over to the local docs repo. +The workflow described below will create the API docs. A formatting script is used to do a bit of cleanup and then copy +the resulting file over to the local docs repo. ```bash # clone the docs repo @@ -28,4 +28,4 @@ pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md python api_doc_mods.py --autogen_path api_temp.md --outpath ../../nebari-docs/docs/docs/references/api_docs.md ``` -Now you are ready to open up a PR with these changes. \ No newline at end of file +Now you are ready to open up a PR with these changes. diff --git a/docs/api_docs/api_doc.md b/docs/api_docs/api_doc.md index 53a3a8e08..b7d5e06a1 100644 --- a/docs/api_docs/api_doc.md +++ b/docs/api_docs/api_doc.md @@ -100,11 +100,11 @@ Get the hex digest of the given file def set_env_vars_in_config(config) ``` -For values in the config starting with 'QHUB_SECRET_XXX' the environment variables are searched for the pattern XXX and the config value is modified. This enables setting secret -values that should not be directly stored in the config file. +For values in the config starting with 'QHUB_SECRET_XXX' the environment variables are searched for the pattern XXX and +the config value is modified. This enables setting secret values that should not be directly stored in the config file. -NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of any of these variables you might consider preventing storage -of the terraform render output. +NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of +any of these variables you might consider preventing storage of the terraform render output. @@ -318,8 +318,8 @@ Create and initialize your \[purple\]nebari-config.yaml\[/purple\] file. This command will create and initialize your \[purple\]nebari-config.yaml\[/purple\] :sparkles: -This file contains all your Nebari cluster configuration details and, is used as input to later commands such as \[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], -etc. +This file contains all your Nebari cluster configuration details and, is used as input to later commands such as +\[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], etc. If you're new to Nebari, we recommend you use the Guided Init wizard. To get started simply run: @@ -495,9 +495,11 @@ def cost(path: str = typer.Option( )) ``` -Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. \[italic\]Experimental.\[/italic\] +Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. +\[italic\]Experimental.\[/italic\] -\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does not include usage costs.\[/italic\] +\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does +not include usage costs.\[/italic\] @@ -523,8 +525,9 @@ def upgrade( Upgrade your \[purple\]nebari-config.yaml\[/purple\] from pre-0.4.0 to 0.4.0. -Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your \[purple\]nebari-config.yaml\[/purple\] to comply with the -introduced changes. See the project \[green\]RELEASE.md\[/green\] for details. +Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your +\[purple\]nebari-config.yaml\[/purple\] to comply with the introduced changes. See the project +\[green\]RELEASE.md\[/green\] for details. @@ -548,4 +551,5 @@ def support(config_filename: str = typer.Option( Support tool to write all Kubernetes logs locally and compress them into a zip file. -The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally helpful for debugging purposes should the logs need to be shared. +The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally +helpful for debugging purposes should the logs need to be shared. From e59510fc5411881286354ec7249a25278f84cda9 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Wed, 14 Dec 2022 13:20:55 -0600 Subject: [PATCH 07/28] merge conflicts --- docs/api_docs/README.md | 9 +- docs/api_docs/api_doc.md | 321 +++++++++++++++++++-------------------- 2 files changed, 155 insertions(+), 175 deletions(-) diff --git a/docs/api_docs/README.md b/docs/api_docs/README.md index c3c314a04..8063b6d57 100644 --- a/docs/api_docs/README.md +++ b/docs/api_docs/README.md @@ -14,18 +14,13 @@ pip install -e ".[docs]" The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI. -The workflow described below will create the API docs. A formatting script is used to do a bit of cleanup and then copy -the resulting file over to the local docs repo. +The workflow described below will create the API docs and run a formatting script to do a bit of cleanup. ```bash -# clone the docs repo -git clone git@github.com:nebari-dev/nebari-docs.git # work out of the api_docs directory in the nebari repo cd docs/api_docs/ # auto generate the api docs pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md # make formatting modifications and copy into the docs repo -python api_doc_mods.py --autogen_path api_temp.md --outpath ../../nebari-docs/docs/docs/references/api_docs.md +python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md ``` - -Now you are ready to open up a PR with these changes. diff --git a/docs/api_docs/api_doc.md b/docs/api_docs/api_doc.md index b7d5e06a1..de68fd6db 100644 --- a/docs/api_docs/api_doc.md +++ b/docs/api_docs/api_doc.md @@ -1,58 +1,62 @@ -______________________________________________________________________ - -## title: API Documentation description: Reference to API docs - -\<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation - +--- +title: API Documentation +description: Reference to API docs +--- +<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation ## Table of Contents - -### qhub.destroy + - +# nebari.destroy -### qhub.initialize + - +# nebari.initialize -### qhub.render + - +# nebari.render -#### render_contents + + +#### render\_contents ```python def render_contents(config: Dict) ``` -Dynamically generated contents from QHub configuration +Dynamically generated contents from Nebari configuration - + -#### gen_gitignore +#### gen\_gitignore ```python def gen_gitignore(config) ``` -Generate `.gitignore` file. Add files as needed. +Generate `.gitignore` file. +Add files as needed. - + -#### gen_cicd +#### gen\_cicd ```python def gen_cicd(config) ``` -Use cicd schema to generate workflow files based on the `ci_cd` key in the `config`. +Use cicd schema to generate workflow files based on the +`ci_cd` key in the `config`. -For more detail on schema: GiHub-Actions - qhub/providers/cicd/github.py GitLab-CI - qhub/providers/cicd/gitlab.py +For more detail on schema: +GiHub-Actions - nebari/providers/cicd/github.py +GitLab-CI - nebari/providers/cicd/gitlab.py - + -#### inspect_files +#### inspect\_files ```python def inspect_files(source_dirs: str, @@ -73,14 +77,14 @@ Return created, updated and untracked files by computing a checksum over the pro - `output_dirs` _str_ - The destination dir which will be matched with - `source_base_dir` _str_ - Relative base path to source directory - `output_base_dir` _str_ - Relative base path to output directory -- `ignore_filenames` _list\[str\]_ - Filenames to ignore while comparing for changes -- `ignore_directories` _list\[str\]_ - Directories to ignore while comparing for changes -- `deleted_paths` _list\[str\]_ - Paths that if exist in output directory should be deleted +- `ignore_filenames` _list[str]_ - Filenames to ignore while comparing for changes +- `ignore_directories` _list[str]_ - Directories to ignore while comparing for changes +- `deleted_paths` _list[str]_ - Paths that if exist in output directory should be deleted - `contents` _dict_ - filename to content mapping for dynamically generated files - + -#### hash_file +#### hash\_file ```python def hash_file(file_path: str) @@ -92,157 +96,124 @@ Get the hex digest of the given file - `file_path` _str_ - path to file - + -#### set_env_vars_in_config +#### set\_env\_vars\_in\_config ```python def set_env_vars_in_config(config) ``` -For values in the config starting with 'QHUB_SECRET_XXX' the environment variables are searched for the pattern XXX and -the config value is modified. This enables setting secret values that should not be directly stored in the config file. - -NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of -any of these variables you might consider preventing storage of the terraform render output. - - +For values in the config starting with 'NEBARI_SECRET_XXX' the environment +variables are searched for the pattern XXX and the config value is +modified. This enables setting secret values that should not be directly +stored in the config file. -### qhub.cli.support +NOTE: variables are most likely written to a file somewhere upon render. In +order to further reduce risk of exposure of any of these variables you might +consider preventing storage of the terraform render output. - + -### qhub.cli.deploy +# nebari.cli - + -### qhub.cli.\_init +# nebari.cli.keycloak - + -#### handle_init +#### add\_user ```python -def handle_init(inputs: InitInputs) +@app_keycloak.command(name="adduser") +def add_user(add_users: Tuple[str, str] = typer.Option( + ..., "--user", help="Provide both: "), + config_filename: str = typer.Option( + ..., + "-c", + "--config", + help="nebari configuration file path", + )) ``` -Take the inputs from the `nebari init` command, render the config and write it to a local yaml file. +Add a user to Keycloak. User will be automatically added to the [italic]analyst[/italic] group. - + -#### check_cloud_provider_creds +#### list\_users ```python -def check_cloud_provider_creds(ctx: typer.Context, cloud_provider: str) +@app_keycloak.command(name="listusers") +def list_users(config_filename: str = typer.Option( + ..., + "-c", + "--config", + help="nebari configuration file path", +)) ``` -Validate that the necessary cloud credentials have been set as environment variables. +List the users in Keycloak. - + -#### check_auth_provider_creds +# nebari.cli.init -```python -def check_auth_provider_creds(ctx: typer.Context, auth_provider: str) -``` + -Validating the the necessary auth provider credentials have been set as environment variables. - - - -#### check_project_name +#### handle\_init ```python -def check_project_name(ctx: typer.Context, project_name: str) +def handle_init(inputs: InitInputs) ``` -Validate the project_name is acceptable. Depends on `cloud_provider`. +Take the inputs from the `nebari init` command, render the config and write it to a local yaml file. - + -#### guided_init_wizard +#### check\_cloud\_provider\_creds ```python -def guided_init_wizard(ctx: typer.Context, guided_init: str) +def check_cloud_provider_creds(ctx: typer.Context, cloud_provider: str) ``` -Guided Init Wizard is a user-friendly questionnaire used to help generate the `nebari-config.yaml`. - - - -### qhub.cli.destroy - - - -### qhub.cli.initialize - - - -### qhub.cli.render - - - -### qhub.cli - - - -### qhub.cli.upgrade - - - -### qhub.cli.validate - - - -### qhub.cli.\_keycloak +Validate that the necessary cloud credentials have been set as environment variables. - + -#### add_user +#### check\_auth\_provider\_creds ```python -@app_keycloak.command(name="adduser") -def add_user(add_users: Tuple[str, str] = typer.Option( - ..., "--user", help="Provide both: "), - config_filename: str = typer.Option( - ..., - "-c", - "--config", - help="qhub configuration file path", - )) +def check_auth_provider_creds(ctx: typer.Context, auth_provider: str) ``` -Add a user to Keycloak. User will be automatically added to the \[italic\]analyst\[/italic\] group. +Validating the the necessary auth provider credentials have been set as environment variables. - + -#### list_users +#### check\_project\_name ```python -@app_keycloak.command(name="listusers") -def list_users(config_filename: str = typer.Option( - ..., - "-c", - "--config", - help="qhub configuration file path", -)) +def check_project_name(ctx: typer.Context, project_name: str) ``` -List the users in Keycloak. +Validate the project_name is acceptable. Depends on `cloud_provider`. - + -### qhub.cli.keycloak +#### guided\_init\_wizard - +```python +def guided_init_wizard(ctx: typer.Context, guided_init: str) +``` -### qhub.cli.cost +Guided Init Wizard is a user-friendly questionnaire used to help generate the `nebari-config.yaml`. - + -### qhub.cli.main +# nebari.cli.main - + ## OrderCommands Objects @@ -250,9 +221,9 @@ List the users in Keycloak. class OrderCommands(TyperGroup) ``` - + -#### list_commands +#### list\_commands ```python def list_commands(ctx: Context) @@ -260,7 +231,7 @@ def list_commands(ctx: Context) Return list of commands in the order appear. - + #### init @@ -307,27 +278,29 @@ def init(cloud_provider: str = typer.Argument( terraform_state: str = typer.Option( "remote", help=f"options: {enum_to_list(TerraformStateEnum)}"), kubernetes_version: str = typer.Option("latest", ), - ssl_cert_email: str = typer.Option(None, ), + ssl_cert_email: str = typer.Option( + None, + callback=check_ssl_cert_email, + ), disable_prompt: bool = typer.Option( False, is_eager=True, )) ``` -Create and initialize your \[purple\]nebari-config.yaml\[/purple\] file. +Create and initialize your [purple]nebari-config.yaml[/purple] file. -This command will create and initialize your \[purple\]nebari-config.yaml\[/purple\] :sparkles: +This command will create and initialize your [purple]nebari-config.yaml[/purple] :sparkles: -This file contains all your Nebari cluster configuration details and, is used as input to later commands such as -\[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], etc. +This file contains all your Nebari cluster configuration details and, +is used as input to later commands such as [green]nebari render[/green], [green]nebari deploy[/green], etc. -If you're new to Nebari, we recommend you use the Guided Init wizard. To get started simply run: +If you're new to Nebari, we recommend you use the Guided Init wizard. +To get started simply run: -``` - [green]nebari init --guided-init[/green] -``` + [green]nebari init --guided-init[/green] - + #### validate @@ -338,17 +311,17 @@ def validate(config: str = typer.Option( "--config", "-c", help= - "qhub configuration yaml file path, please pass in as -c/--config flag", + "nebari configuration yaml file path, please pass in as -c/--config flag", ), enable_commenting: bool = typer.Option( False, - "--enable_commenting", + "--enable-commenting", help="Toggle PR commenting on GitHub Actions")) ``` -Validate the values in the \[purple\]nebari-config.yaml\[/purple\] file are acceptable. +Validate the values in the [purple]nebari-config.yaml[/purple] file are acceptable. - + #### render @@ -376,9 +349,9 @@ def render( )) ``` -Dynamically render the Terraform scripts and other files from your \[purple\]nebari-config.yaml\[/purple\] file. +Dynamically render the Terraform scripts and other files from your [purple]nebari-config.yaml[/purple] file. - + #### deploy @@ -407,7 +380,7 @@ def deploy( False, "--dns-auto-provision", help= - "Attempt to automatically provision DNS. For Auth0 is requires environment variables AUTH0_DOMAIN, AUTH0_CLIENTID, AUTH0_CLIENT_SECRET", + "Attempt to automatically provision DNS, currently only available for `cloudflare`", ), disable_prompt: bool = typer.Option( False, @@ -418,12 +391,24 @@ def deploy( False, "--disable-render", help="Disable auto-rendering in deploy stage", - )) + ), + disable_checks: bool = typer.Option( + False, + "--disable-checks", + help="Disable the checks performed after each stage", + ), + skip_remote_state_provision: bool = typer. + Option( + False, + "--skip-remote-state-provision", + help= + "Skip terraform state deployment which is often required in CI once the terraform remote state bootstrapping phase is complete", + )) ``` -Deploy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. +Deploy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. - + #### destroy @@ -433,9 +418,9 @@ def destroy( config: str = typer.Option(..., "-c", "--config", - help="qhub configuration file path"), + help="nebari configuration file path"), output: str = typer.Option( - "./" + "./", "-o", "--output", help="output directory", @@ -454,9 +439,9 @@ def destroy( )) ``` -Destroy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. +Destroy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. - + #### cost @@ -467,7 +452,7 @@ def cost(path: str = typer.Option( "-p", "--path", help= - "Pass the path of your stages directory generated after rendering QHub configurations before deployment", + "Pass the path of your stages directory generated after rendering Nebari configurations before deployment", ), dashboard: bool = typer.Option( True, @@ -495,13 +480,12 @@ def cost(path: str = typer.Option( )) ``` -Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. -\[italic\]Experimental.\[/italic\] +Estimate the cost of deploying Nebari based on your [purple]nebari-config.yaml[/purple]. [italic]Experimental.[/italic] -\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does -not include usage costs.\[/italic\] +[italic]This is still only experimental using Infracost under the hood. +The estimated value is a base cost and does not include usage costs.[/italic] - + #### upgrade @@ -512,24 +496,24 @@ def upgrade( ..., "-c", "--config", - help="qhub configuration file path", + help="nebari configuration file path", ), attempt_fixes: bool = typer. Option( False, "--attempt-fixes", help= - "Attempt to fix the config for any incompatibilities between your old and new QHub versions.", + "Attempt to fix the config for any incompatibilities between your old and new Nebari versions.", )) ``` -Upgrade your \[purple\]nebari-config.yaml\[/purple\] from pre-0.4.0 to 0.4.0. +Upgrade your [purple]nebari-config.yaml[/purple] from pre-0.4.0 to 0.4.0. -Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your -\[purple\]nebari-config.yaml\[/purple\] to comply with the introduced changes. See the project -\[green\]RELEASE.md\[/green\] for details. +Due to several breaking changes that came with the 0.4.0 release, this utility is available to help +update your [purple]nebari-config.yaml[/purple] to comply with the introduced changes. +See the project [green]RELEASE.md[/green] for details. - + #### support @@ -539,10 +523,10 @@ def support(config_filename: str = typer.Option( ..., "-c", "--config", - help="qhub configuration file path", + help="nebari configuration file path", ), output: str = typer.Option( - "./qhub-support-logs.zip", + "./nebari-support-logs.zip", "-o", "--output", help="output filename", @@ -551,5 +535,6 @@ def support(config_filename: str = typer.Option( Support tool to write all Kubernetes logs locally and compress them into a zip file. -The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally -helpful for debugging purposes should the logs need to be shared. +The Nebari team recommends k9s to manage and inspect the state of the cluster. +However, this command occasionally helpful for debugging purposes should the logs need to be shared. + From 29ef6e9b862bcf7c02a3c82270b7f73860db2ae0 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Wed, 14 Dec 2022 13:12:23 -0600 Subject: [PATCH 08/28] remove conda from ci, update readme, finish rename --- .github/workflows/update_api_docs.yml | 18 ++--- docs/api_docs/README.md | 2 + docs/api_docs/api_doc.md | 108 ++++++++++++-------------- docs/api_docs/api_doc_mods.py | 31 ++++---- setup.cfg | 1 + 5 files changed, 75 insertions(+), 85 deletions(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index 2dc10b125..294a2db07 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -18,19 +18,15 @@ jobs: - name: Check out repository 🛎️ uses: actions/checkout@v3 - - name: Install conda dependencies - uses: conda-incubator/setup-miniconda@v2 + - name: Set up Python + uses: actions/setup-python@v1 with: - python-version: "3.10" - activate-environment: nebari-dev - environment-file: environment-dev.yaml - auto-activate-base: true + python-version: 3.10 - name: Install nebari and docs dependencies - run: pip install -e "../..[docs]" - - - name: Conda list - run: conda list + run: | + python -m pip install --upgrade pip + pip install -e "../..[docs]" - name: Look for changes to cli files uses: tj-actions/verify-changed-files@v12 @@ -50,6 +46,8 @@ jobs: pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md echo "make modifications to clean up" python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md + echo "run linting and formatting" + pre-commit run --files api_doc.md - name: Check for changes run: | diff --git a/docs/api_docs/README.md b/docs/api_docs/README.md index 8063b6d57..aa3a06028 100644 --- a/docs/api_docs/README.md +++ b/docs/api_docs/README.md @@ -23,4 +23,6 @@ cd docs/api_docs/ pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md # make formatting modifications and copy into the docs repo python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md +# run linting and formatting +pre-commit run --files api_doc.md ``` diff --git a/docs/api_docs/api_doc.md b/docs/api_docs/api_doc.md index de68fd6db..799025bb9 100644 --- a/docs/api_docs/api_doc.md +++ b/docs/api_docs/api_doc.md @@ -1,10 +1,10 @@ ---- -title: API Documentation -description: Reference to API docs ---- -<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation -## Table of Contents +______________________________________________________________________ + +## title: API Documentation description: Reference to API docs +\<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation + +## Table of Contents @@ -20,7 +20,7 @@ description: Reference to API docs -#### render\_contents +#### render_contents ```python def render_contents(config: Dict) @@ -30,33 +30,29 @@ Dynamically generated contents from Nebari configuration -#### gen\_gitignore +#### gen_gitignore ```python def gen_gitignore(config) ``` -Generate `.gitignore` file. -Add files as needed. +Generate `.gitignore` file. Add files as needed. -#### gen\_cicd +#### gen_cicd ```python def gen_cicd(config) ``` -Use cicd schema to generate workflow files based on the -`ci_cd` key in the `config`. +Use cicd schema to generate workflow files based on the `ci_cd` key in the `config`. -For more detail on schema: -GiHub-Actions - nebari/providers/cicd/github.py -GitLab-CI - nebari/providers/cicd/gitlab.py +For more detail on schema: GiHub-Actions - nebari/providers/cicd/github.py GitLab-CI - nebari/providers/cicd/gitlab.py -#### inspect\_files +#### inspect_files ```python def inspect_files(source_dirs: str, @@ -77,14 +73,14 @@ Return created, updated and untracked files by computing a checksum over the pro - `output_dirs` _str_ - The destination dir which will be matched with - `source_base_dir` _str_ - Relative base path to source directory - `output_base_dir` _str_ - Relative base path to output directory -- `ignore_filenames` _list[str]_ - Filenames to ignore while comparing for changes -- `ignore_directories` _list[str]_ - Directories to ignore while comparing for changes -- `deleted_paths` _list[str]_ - Paths that if exist in output directory should be deleted +- `ignore_filenames` _list\[str\]_ - Filenames to ignore while comparing for changes +- `ignore_directories` _list\[str\]_ - Directories to ignore while comparing for changes +- `deleted_paths` _list\[str\]_ - Paths that if exist in output directory should be deleted - `contents` _dict_ - filename to content mapping for dynamically generated files -#### hash\_file +#### hash_file ```python def hash_file(file_path: str) @@ -98,20 +94,17 @@ Get the hex digest of the given file -#### set\_env\_vars\_in\_config +#### set_env_vars_in_config ```python def set_env_vars_in_config(config) ``` -For values in the config starting with 'NEBARI_SECRET_XXX' the environment -variables are searched for the pattern XXX and the config value is -modified. This enables setting secret values that should not be directly -stored in the config file. +For values in the config starting with 'NEBARI_SECRET_XXX' the environment variables are searched for the pattern XXX and the config value is modified. This enables setting secret +values that should not be directly stored in the config file. -NOTE: variables are most likely written to a file somewhere upon render. In -order to further reduce risk of exposure of any of these variables you might -consider preventing storage of the terraform render output. +NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of any of these variables you might consider preventing storage +of the terraform render output. @@ -123,7 +116,7 @@ consider preventing storage of the terraform render output. -#### add\_user +#### add_user ```python @app_keycloak.command(name="adduser") @@ -137,11 +130,11 @@ def add_user(add_users: Tuple[str, str] = typer.Option( )) ``` -Add a user to Keycloak. User will be automatically added to the [italic]analyst[/italic] group. +Add a user to Keycloak. User will be automatically added to the \[italic\]analyst\[/italic\] group. -#### list\_users +#### list_users ```python @app_keycloak.command(name="listusers") @@ -161,7 +154,7 @@ List the users in Keycloak. -#### handle\_init +#### handle_init ```python def handle_init(inputs: InitInputs) @@ -171,7 +164,7 @@ Take the inputs from the `nebari init` command, render the config and write it t -#### check\_cloud\_provider\_creds +#### check_cloud_provider_creds ```python def check_cloud_provider_creds(ctx: typer.Context, cloud_provider: str) @@ -181,7 +174,7 @@ Validate that the necessary cloud credentials have been set as environment varia -#### check\_auth\_provider\_creds +#### check_auth_provider_creds ```python def check_auth_provider_creds(ctx: typer.Context, auth_provider: str) @@ -191,7 +184,7 @@ Validating the the necessary auth provider credentials have been set as environm -#### check\_project\_name +#### check_project_name ```python def check_project_name(ctx: typer.Context, project_name: str) @@ -201,7 +194,7 @@ Validate the project_name is acceptable. Depends on `cloud_provider`. -#### guided\_init\_wizard +#### guided_init_wizard ```python def guided_init_wizard(ctx: typer.Context, guided_init: str) @@ -223,7 +216,7 @@ class OrderCommands(TyperGroup) -#### list\_commands +#### list_commands ```python def list_commands(ctx: Context) @@ -288,17 +281,18 @@ def init(cloud_provider: str = typer.Argument( )) ``` -Create and initialize your [purple]nebari-config.yaml[/purple] file. +Create and initialize your \[purple\]nebari-config.yaml\[/purple\] file. -This command will create and initialize your [purple]nebari-config.yaml[/purple] :sparkles: +This command will create and initialize your \[purple\]nebari-config.yaml\[/purple\] :sparkles: -This file contains all your Nebari cluster configuration details and, -is used as input to later commands such as [green]nebari render[/green], [green]nebari deploy[/green], etc. +This file contains all your Nebari cluster configuration details and, is used as input to later commands such as \[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], +etc. -If you're new to Nebari, we recommend you use the Guided Init wizard. -To get started simply run: +If you're new to Nebari, we recommend you use the Guided Init wizard. To get started simply run: - [green]nebari init --guided-init[/green] +``` + [green]nebari init --guided-init[/green] +``` @@ -319,7 +313,7 @@ def validate(config: str = typer.Option( help="Toggle PR commenting on GitHub Actions")) ``` -Validate the values in the [purple]nebari-config.yaml[/purple] file are acceptable. +Validate the values in the \[purple\]nebari-config.yaml\[/purple\] file are acceptable. @@ -349,7 +343,7 @@ def render( )) ``` -Dynamically render the Terraform scripts and other files from your [purple]nebari-config.yaml[/purple] file. +Dynamically render the Terraform scripts and other files from your \[purple\]nebari-config.yaml\[/purple\] file. @@ -406,7 +400,7 @@ def deploy( )) ``` -Deploy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. +Deploy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. @@ -439,7 +433,7 @@ def destroy( )) ``` -Destroy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file. +Destroy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. @@ -480,10 +474,9 @@ def cost(path: str = typer.Option( )) ``` -Estimate the cost of deploying Nebari based on your [purple]nebari-config.yaml[/purple]. [italic]Experimental.[/italic] +Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. \[italic\]Experimental.\[/italic\] -[italic]This is still only experimental using Infracost under the hood. -The estimated value is a base cost and does not include usage costs.[/italic] +\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does not include usage costs.\[/italic\] @@ -507,11 +500,10 @@ def upgrade( )) ``` -Upgrade your [purple]nebari-config.yaml[/purple] from pre-0.4.0 to 0.4.0. +Upgrade your \[purple\]nebari-config.yaml\[/purple\] from pre-0.4.0 to 0.4.0. -Due to several breaking changes that came with the 0.4.0 release, this utility is available to help -update your [purple]nebari-config.yaml[/purple] to comply with the introduced changes. -See the project [green]RELEASE.md[/green] for details. +Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your \[purple\]nebari-config.yaml\[/purple\] to comply with the +introduced changes. See the project \[green\]RELEASE.md\[/green\] for details. @@ -535,6 +527,4 @@ def support(config_filename: str = typer.Option( Support tool to write all Kubernetes logs locally and compress them into a zip file. -The Nebari team recommends k9s to manage and inspect the state of the cluster. -However, this command occasionally helpful for debugging purposes should the logs need to be shared. - +The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally helpful for debugging purposes should the logs need to be shared. diff --git a/docs/api_docs/api_doc_mods.py b/docs/api_docs/api_doc_mods.py index dc2690d67..c31fc8a51 100644 --- a/docs/api_docs/api_doc_mods.py +++ b/docs/api_docs/api_doc_mods.py @@ -46,23 +46,23 @@ def modify_autogen_api_docs(autogen_path: Path, outpath: Path) -> None: # fix header flags (otherwise page nav won't work) for idx, line in enumerate(text): - if line[0:7] == "# qhub.": + if line[0:7] == "# nebari.": text[idx] = "##" + line - elif line == "# qhub\n": - text[idx] = "## qhub\n" + elif line == "# nebari\n": + text[idx] = "## nebari\n" keep_docs = [ - '"qhub.initialize', - '"qhub.cli.deploy', - '"qhub.cli.destroy', - '"qhub.cli.initialize', - '"qhub.cli.render', - '"qhub.cli.support', - '"qhub.cli', - '"qhub.cli.upgrade', - '"qhub.cli.validate', - '"qhub.render', - '"qhub.destroy', + '"nebari.initialize', + '"nebari.cli.deploy', + '"nebari.cli.destroy', + '"nebari.cli.initialize', + '"nebari.cli.render', + '"nebari.cli.support', + '"nebari.cli', + '"nebari.cli.upgrade', + '"nebari.cli.validate', + '"nebari.render', + '"nebari.destroy', ] id_idx = [] @@ -88,10 +88,9 @@ def modify_autogen_api_docs(autogen_path: Path, outpath: Path) -> None: all_headers = zip(keep_idx, offset_idx) map = dict(zip(keep_idx, all_headers)) - # for idx in keep_idx: for idx, group in map.items(): clean_list.extend(text[slice(*group)]) - print(Path(outpath).resolve()) + if not Path(outpath).exists: print(Path(outpath).resolve()) diff --git a/setup.cfg b/setup.cfg index 201c0c226..71d62135f 100644 --- a/setup.cfg +++ b/setup.cfg @@ -65,6 +65,7 @@ dev = docs = novella pydoc-markdown + pre-commit [options.entry_points] console_scripts = From a64666f3eb5b6570c2ba057d14e932560e5c3e33 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 14 Dec 2022 19:27:11 +0000 Subject: [PATCH 09/28] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/api_docs/api_doc.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/docs/api_docs/api_doc.md b/docs/api_docs/api_doc.md index 799025bb9..d421af4eb 100644 --- a/docs/api_docs/api_doc.md +++ b/docs/api_docs/api_doc.md @@ -100,11 +100,12 @@ Get the hex digest of the given file def set_env_vars_in_config(config) ``` -For values in the config starting with 'NEBARI_SECRET_XXX' the environment variables are searched for the pattern XXX and the config value is modified. This enables setting secret -values that should not be directly stored in the config file. +For values in the config starting with 'NEBARI_SECRET_XXX' the environment variables are searched for the pattern XXX +and the config value is modified. This enables setting secret values that should not be directly stored in the config +file. -NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of any of these variables you might consider preventing storage -of the terraform render output. +NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of +any of these variables you might consider preventing storage of the terraform render output. @@ -285,8 +286,8 @@ Create and initialize your \[purple\]nebari-config.yaml\[/purple\] file. This command will create and initialize your \[purple\]nebari-config.yaml\[/purple\] :sparkles: -This file contains all your Nebari cluster configuration details and, is used as input to later commands such as \[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], -etc. +This file contains all your Nebari cluster configuration details and, is used as input to later commands such as +\[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], etc. If you're new to Nebari, we recommend you use the Guided Init wizard. To get started simply run: @@ -474,9 +475,11 @@ def cost(path: str = typer.Option( )) ``` -Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. \[italic\]Experimental.\[/italic\] +Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. +\[italic\]Experimental.\[/italic\] -\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does not include usage costs.\[/italic\] +\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does +not include usage costs.\[/italic\] @@ -502,8 +505,9 @@ def upgrade( Upgrade your \[purple\]nebari-config.yaml\[/purple\] from pre-0.4.0 to 0.4.0. -Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your \[purple\]nebari-config.yaml\[/purple\] to comply with the -introduced changes. See the project \[green\]RELEASE.md\[/green\] for details. +Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your +\[purple\]nebari-config.yaml\[/purple\] to comply with the introduced changes. See the project +\[green\]RELEASE.md\[/green\] for details. @@ -527,4 +531,5 @@ def support(config_filename: str = typer.Option( Support tool to write all Kubernetes logs locally and compress them into a zip file. -The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally helpful for debugging purposes should the logs need to be shared. +The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally +helpful for debugging purposes should the logs need to be shared. From dc9740025032baa3cd3c71ff1da5f26e7afeb9e1 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Wed, 14 Dec 2022 13:28:21 -0600 Subject: [PATCH 10/28] formatting --- .github/workflows/update_api_docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index 294a2db07..3ceecd191 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -21,7 +21,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v1 with: - python-version: 3.10 + python-version: "3.10" - name: Install nebari and docs dependencies run: | From 165d730c00e16f35b9748fda33acea1a213d2f65 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Wed, 14 Dec 2022 14:45:31 -0600 Subject: [PATCH 11/28] allow precommit to error in order to lint --- .github/workflows/update_api_docs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index 3ceecd191..4fcb356af 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -46,8 +46,14 @@ jobs: pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md echo "make modifications to clean up" python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md + + - name: Lint the new docs + run: | + set -e echo "run linting and formatting" pre-commit run --files api_doc.md + echo "run it again to prove its clean now" + pre-commit run --files api_doc.md - name: Check for changes run: | From 8b8f817f02369f4b611200234b6860f4457dfb37 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Thu, 15 Dec 2022 13:25:21 -0600 Subject: [PATCH 12/28] try continue-on-error --- .github/workflows/update_api_docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index 4fcb356af..de5cfc326 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -48,8 +48,8 @@ jobs: python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md - name: Lint the new docs + continue-on-error: true run: | - set -e echo "run linting and formatting" pre-commit run --files api_doc.md echo "run it again to prove its clean now" From 09c153e322bee36bdec0bd856bcd6afde6b35091 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Thu, 15 Dec 2022 13:33:50 -0600 Subject: [PATCH 13/28] move docs requirements into pyproject.toml --- pyproject.toml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 3beda30e7..26049f74d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -82,6 +82,11 @@ dev = [ "pytest", "pytest-timeout", ] +docs = [ + "novella", + "pydoc-markdown", + "pre-commit" +] [project.urls] Documentation = "https://www.nebari.dev/docs" From c1e338b8ed9bd937c262be34bf9584c869568b7d Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Thu, 15 Dec 2022 13:39:46 -0600 Subject: [PATCH 14/28] security hooha --- .github/workflows/update_api_docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index de5cfc326..e0626a0f2 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -58,9 +58,9 @@ jobs: - name: Check for changes run: | if git diff --exit-code; then - echo "::set-env name=changes_exist::true" + echo "changes_exist=true" >> $GITHUB_ENV else - echo "::set-env name=changes_exist::false" + echo "changes_exist=false" >> $GITHUB_ENV fi - name: Create Pull Request in code repo From 5e4dca65a3e0a3791e715d807af80e5a6dd84162 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Thu, 15 Dec 2022 13:45:41 -0600 Subject: [PATCH 15/28] modify the watch for changes --- .github/workflows/update_api_docs.yml | 23 +++++++++-------------- 1 file changed, 9 insertions(+), 14 deletions(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index e0626a0f2..a3f08fda7 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -28,18 +28,6 @@ jobs: python -m pip install --upgrade pip pip install -e "../..[docs]" - - name: Look for changes to cli files - uses: tj-actions/verify-changed-files@v12 - id: verify-changed-files - with: - files: | - nebari/cli/* - - - name: Look for file changes - if: steps.verify-changed-files.outputs.files_changed == 'true' - run: | - echo "Changed files: ${{ steps.verify-changed-files.outputs.changed_files }}" - - name: Generate new API docs run: | echo "generate the new docs" @@ -63,10 +51,17 @@ jobs: echo "changes_exist=false" >> $GITHUB_ENV fi + - name: Look for changes to cli files + uses: tj-actions/verify-changed-files@v12 + id: verify-changed-files + with: + files: | + docs/api_docs/api_doc.md + - name: Create Pull Request in code repo - id: cpr + id: create_pull_request uses: peter-evans/create-pull-request@v4 - if: ${{ env.changes_exist == 'true' }} + if: steps.verify-changed-files.outputs.files_changed == 'true' with: token: ${{ secrets.NEBARI_SENSEI_API_DOCS_PR_OPENER }} commit-message: Update report From 23006ad3cf0195ece8570bb987d1cfeced24dd70 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Mon, 23 Jan 2023 11:54:13 -0600 Subject: [PATCH 16/28] Update pyproject.toml --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 26049f74d..b8aedb588 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -85,7 +85,7 @@ dev = [ docs = [ "novella", "pydoc-markdown", - "pre-commit" + "pre-commit", ] [project.urls] From 2db398b248b7f7234fbf8a1818c2699b9489de39 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Tue, 31 Jan 2023 14:00:48 -0600 Subject: [PATCH 17/28] specify base branch --- .github/workflows/update_api_docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index a3f08fda7..fc68fa718 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -79,3 +79,4 @@ jobs: labels: | "area: documentation 📖" draft: false + base: ${{ github.head_ref }} From 3418079f1c2c325b6043e13f3cda7e5b5770b818 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Fri, 10 Mar 2023 10:46:22 -0600 Subject: [PATCH 18/28] cleanup --- .github/workflows/update_api_docs.yml | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index fc68fa718..3e76c9e40 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -43,15 +43,7 @@ jobs: echo "run it again to prove its clean now" pre-commit run --files api_doc.md - - name: Check for changes - run: | - if git diff --exit-code; then - echo "changes_exist=true" >> $GITHUB_ENV - else - echo "changes_exist=false" >> $GITHUB_ENV - fi - - - name: Look for changes to cli files + - name: Look for changes to generated docss uses: tj-actions/verify-changed-files@v12 id: verify-changed-files with: @@ -64,7 +56,7 @@ jobs: if: steps.verify-changed-files.outputs.files_changed == 'true' with: token: ${{ secrets.NEBARI_SENSEI_API_DOCS_PR_OPENER }} - commit-message: Update report + commit-message: Update api docs committer: GitHub author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com> signoff: false From 81aebf5ed9ed7ae49357e39cab2e41aac73b66b4 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Mon, 20 Mar 2023 09:41:42 -0500 Subject: [PATCH 19/28] switching to sphinx-click --- .github/workflows/update_api_docs.yml | 25 +++++++++---------------- .gitignore | 1 - nebari/cli/main.py | 9 ++++++++- pyproject.toml | 6 +++--- 4 files changed, 20 insertions(+), 21 deletions(-) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/update_api_docs.yml index 3e76c9e40..e72206a10 100644 --- a/.github/workflows/update_api_docs.yml +++ b/.github/workflows/update_api_docs.yml @@ -13,7 +13,7 @@ jobs: defaults: run: shell: bash -l {0} - working-directory: ./docs/api_docs + working-directory: ./docs/docs-sphinx steps: - name: Check out repository 🛎️ uses: actions/checkout@v3 @@ -30,25 +30,18 @@ jobs: - name: Generate new API docs run: | - echo "generate the new docs" - pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md - echo "make modifications to clean up" - python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md + make html - - name: Lint the new docs - continue-on-error: true + - name: Copy cli doc run: | - echo "run linting and formatting" - pre-commit run --files api_doc.md - echo "run it again to prove its clean now" - pre-commit run --files api_doc.md + cp docs-sphinx/_build/html/cli.html docs-sphinx/cli.html - - name: Look for changes to generated docss + - name: Look for changes to generated docs uses: tj-actions/verify-changed-files@v12 id: verify-changed-files with: files: | - docs/api_docs/api_doc.md + docs-sphinx/cli.html - name: Create Pull Request in code repo id: create_pull_request @@ -60,11 +53,11 @@ jobs: committer: GitHub author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com> signoff: false - branch: auto_api_doc_update + branch: auto_cli_doc_update delete-branch: true - title: '[AUTO] Update API doc' + title: '[AUTO] Update CLI doc' body: | - Update API doc + Update CLI doc - Auto-generated by [create-pull-request][1] [1]: https://github.com/peter-evans/create-pull-request diff --git a/.gitignore b/.gitignore index 68665a09c..db9bca57d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ # docs .nox _build -docs/api_docs/api_temp.md # setuptools scm nebari/_version.py diff --git a/nebari/cli/main.py b/nebari/cli/main.py index 2f6d4fb2a..1aef48c60 100644 --- a/nebari/cli/main.py +++ b/nebari/cli/main.py @@ -78,6 +78,7 @@ def list_commands(self, ctx: Context): ) + @app.callback(invoke_without_command=True) def version( version: Optional[bool] = typer.Option( @@ -529,6 +530,12 @@ def support( zip.write(file) +# get the click object from the typer app so that we can autodoc the cli +# NOTE: this must happen _after_ all the subcommands have been added. +# Adapted from https://typer.tiangolo.com/tutorial/using-click/ +typer_click_app = typer.main.get_command(app) + + def get_config_namespace(config): config_filename = Path(config) if not config_filename.is_file(): @@ -543,4 +550,4 @@ def get_config_namespace(config): if __name__ == "__main__": - app() + typer_click_app() diff --git a/pyproject.toml b/pyproject.toml index 99c07f1ca..264166742 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -82,9 +82,9 @@ dev = [ "pytest-timeout", ] docs = [ - "novella", - "pydoc-markdown", - "pre-commit", + [dev], + "sphinx", + "sphinx_click", ] [project.urls] From 1d950b85f3b945997e4620e731e9987a563f4be0 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Mon, 20 Mar 2023 09:42:22 -0500 Subject: [PATCH 20/28] rename file --- .github/workflows/{update_api_docs.yml => generate_cli_doc.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{update_api_docs.yml => generate_cli_doc.yml} (100%) diff --git a/.github/workflows/update_api_docs.yml b/.github/workflows/generate_cli_doc.yml similarity index 100% rename from .github/workflows/update_api_docs.yml rename to .github/workflows/generate_cli_doc.yml From 9cdaf9e5b879aaf4361689f35b5f65c31a763312 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Mon, 20 Mar 2023 09:49:57 -0500 Subject: [PATCH 21/28] add sphinx-click docs --- docs-sphinx/Makefile | 20 ++ docs-sphinx/README.md | 26 ++ docs-sphinx/cli.html | 681 ++++++++++++++++++++++++++++++++++++++++++ docs-sphinx/cli.rst | 6 + docs-sphinx/conf.py | 9 + docs-sphinx/index.rst | 21 ++ pyproject.toml | 1 - 7 files changed, 763 insertions(+), 1 deletion(-) create mode 100644 docs-sphinx/Makefile create mode 100644 docs-sphinx/README.md create mode 100644 docs-sphinx/cli.html create mode 100644 docs-sphinx/cli.rst create mode 100644 docs-sphinx/conf.py create mode 100644 docs-sphinx/index.rst diff --git a/docs-sphinx/Makefile b/docs-sphinx/Makefile new file mode 100644 index 000000000..d4bb2cbb9 --- /dev/null +++ b/docs-sphinx/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs-sphinx/README.md b/docs-sphinx/README.md new file mode 100644 index 000000000..030519a81 --- /dev/null +++ b/docs-sphinx/README.md @@ -0,0 +1,26 @@ +# Nebari CLI documentation + +The CLI docs are generated using Sphinx and the sphinx-click extension. Although +a full Sphinx website is required in order to generate the docs, only the +`cli.html` file is used. This file gets copied over to the nebari-docs repo via +a GitHub Action. + +## Automation via GitHub Actions + +_Generating the CLI HTML file_ + +A GitHub Action will run with every push to either the `dev` or `main` branches +which generates the documentation. A full Sphinx site build is required. To +build the site, go to the `docs-sphinx` folder and run + +`make html` + +The Action will then checks to see if `cli.html` (the generated doc) has +changed. If it has changed, it will open a new PR with an updated version. + +_Updating the Nebari Docs repo_ + +The Nebari Documentation lives in a separate repo from the code itself +(https://github.com/nebari-dev/nebari-docs). A separate GitHub Action watches +for changes to the `cli.html` file in _this_ repo, and keeps it in sync with +the `cli.html` file in the docs repo. diff --git a/docs-sphinx/cli.html b/docs-sphinx/cli.html new file mode 100644 index 000000000..f2c124a71 --- /dev/null +++ b/docs-sphinx/cli.html @@ -0,0 +1,681 @@ + + + + + + + + + cli docs — Nebari CLI documentation documentation + + + + + + + + + + + + + + + + + +
+
+
+ + +
+ +
+

cli docs

+
+

main

+

Nebari CLI 🪴

+
main [OPTIONS] COMMAND [ARGS]...
+
+
+

Options

+
+
+-v, --version
+

Nebari version number

+
+ +
+

cost

+

Estimate the cost of deploying Nebari based on your [purple]nebari-config.yaml[/purple]. [italic]Experimental.[/italic].

+

[italic]This is still only experimental using Infracost under the hood. +The estimated value is a base cost and does not include usage costs.[/italic]

+
main cost [OPTIONS]
+
+
+

Options

+
+
+-p, --path <path>
+

Pass the path of your stages directory generated after rendering Nebari configurations before deployment

+
+ +
+
+-d, --dashboard
+

Enable the cost dashboard

+
+
Default:
+

True

+
+
+
+ +
+
+-f, --file <file>
+

Specify the path of the file to store the cost report

+
+ +
+
+-c, --currency <currency>
+

Specify the currency code to use in the cost report

+
+
Default:
+

USD

+
+
+
+ +
+
+-cc, --compare
+

Compare the cost report to a previously generated report

+
+
Default:
+

False

+
+
+
+ +
+
+

deploy

+

Deploy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file.

+
main deploy [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config>
+

Required nebari configuration yaml file path

+
+ +
+
+-o, --output <output>
+

output directory

+
+
Default:
+

./

+
+
+
+ +
+
+--dns-provider <dns_provider>
+

dns provider to use for registering domain name mapping

+
+
Default:
+

False

+
+
+
+ +
+
+--dns-auto-provision
+

Attempt to automatically provision DNS, currently only available for cloudflare

+
+
Default:
+

False

+
+
+
+ +
+
+--disable-prompt
+

Disable human intervention

+
+
Default:
+

False

+
+
+
+ +
+
+--disable-render
+

Disable auto-rendering in deploy stage

+
+
Default:
+

False

+
+
+
+ +
+
+--disable-checks
+

Disable the checks performed after each stage

+
+
Default:
+

False

+
+
+
+ +
+
+--skip-remote-state-provision
+

Skip terraform state deployment which is often required in CI once the terraform remote state bootstrapping phase is complete

+
+
Default:
+

False

+
+
+
+ +
+
+

destroy

+

Destroy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file.

+
main destroy [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config>
+

Required nebari configuration file path

+
+ +
+
+-o, --output <output>
+

output directory

+
+
Default:
+

./

+
+
+
+ +
+
+--disable-render
+

Disable auto-rendering before destroy

+
+
Default:
+

False

+
+
+
+ +
+
+--disable-prompt
+

Destroy entire Nebari cluster without confirmation request. Suggested for CI use.

+
+
Default:
+

False

+
+
+
+ +
+
+

dev

+

Development tools and advanced features.

+
main dev [OPTIONS] COMMAND [ARGS]...
+
+
+
+

keycloak-api

+

Interact with the Keycloak REST API directly.

+

This is an advanced tool which can have potentially destructive consequences. +Please use this at your own risk.

+
main dev keycloak-api [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config_filename>
+

Required nebari configuration file path

+
+ +
+
+-r, --request <request>
+

Required Send a REST API request, valid requests follow patterns found here: [green]keycloak.org/docs-api/15.0/rest-api[/green]

+
+ +
+
+
+

init

+

Create and initialize your [purple]nebari-config.yaml[/purple] file.

+

This command will create and initialize your [purple]nebari-config.yaml[/purple] :sparkles:

+

This file contains all your Nebari cluster configuration details and, +is used as input to later commands such as [green]nebari render[/green], [green]nebari deploy[/green], etc.

+

If you’re new to Nebari, we recommend you use the Guided Init wizard. +To get started simply run:

+
+

[green]nebari init –guided-init[/green]

+
+
main init [OPTIONS] [CLOUD_PROVIDER]
+
+
+

Options

+
+
+--guided-init, --no-guided-init
+

[bold green]START HERE[/bold green] - this will guide you step-by-step to generate your [purple]nebari-config.yaml[/purple]. It is an [i]alternative[/i] to passing the options listed below.

+
+
Default:
+

False

+
+
+
+ +
+
+-p, --project-name, --project <project_name>
+

Required

+
+ +
+
+-d, --domain-name, --domain <domain_name>
+

Required

+
+ +
+
+--namespace <namespace>
+
+
Default:
+

dev

+
+
+
+ +
+
+--auth-provider <auth_provider>
+

options: [‘password’, ‘github’, ‘auth0’, ‘custom’]

+
+
Default:
+

password

+
+
+
+ +
+
+--auth-auto-provision, --no-auth-auto-provision
+
+
Default:
+

False

+
+
+
+ +
+
+--repository <repository>
+

options: [‘github.com’, ‘gitlab.com’]

+
+ +
+
+--repository-auto-provision, --no-repository-auto-provision
+
+
Default:
+

False

+
+
+
+ +
+
+--ci-provider <ci_provider>
+

options: [‘github-actions’, ‘gitlab-ci’, ‘none’]

+
+ +
+
+--terraform-state <terraform_state>
+

options: [‘remote’, ‘local’, ‘existing’]

+
+
Default:
+

remote

+
+
+
+ +
+
+--kubernetes-version <kubernetes_version>
+
+
Default:
+

latest

+
+
+
+ +
+
+--ssl-cert-email <ssl_cert_email>
+
+ +
+
+--disable-prompt, --no-disable-prompt
+
+
Default:
+

False

+
+
+
+ +

Arguments

+
+
+CLOUD_PROVIDER
+

Optional argument

+
+ +
+
+

keycloak

+

Interact with the Nebari Keycloak identity and access management tool.

+
main keycloak [OPTIONS] COMMAND [ARGS]...
+
+
+
+

adduser

+

Add a user to Keycloak. User will be automatically added to the [italic]analyst[/italic] group.

+
main keycloak adduser [OPTIONS]
+
+
+

Options

+
+
+--user <add_users>
+

Required Provide both: <username> <password>

+
+ +
+
+-c, --config <config_filename>
+

Required nebari configuration file path

+
+ +
+
+

export-users

+

Export the users in Keycloak.

+
main keycloak export-users [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config_filename>
+

Required nebari configuration file path

+
+ +
+
+--realm <realm>
+

realm from which users are to be exported

+
+
Default:
+

nebari

+
+
+
+ +
+
+

listusers

+

List the users in Keycloak.

+
main keycloak listusers [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config_filename>
+

Required nebari configuration file path

+
+ +
+
+
+

render

+

Dynamically render the Terraform scripts and other files from your [purple]nebari-config.yaml[/purple] file.

+
main render [OPTIONS]
+
+
+

Options

+
+
+-o, --output <output>
+

output directory

+
+
Default:
+

./

+
+
+
+ +
+
+-c, --config <config>
+

Required nebari configuration yaml file path

+
+ +
+
+--dry-run
+

simulate rendering files without actually writing or updating any files

+
+
Default:
+

False

+
+
+
+ +
+
+

support

+

Support tool to write all Kubernetes logs locally and compress them into a zip file.

+

The Nebari team recommends k9s to manage and inspect the state of the cluster. +However, this command occasionally helpful for debugging purposes should the logs need to be shared.

+
main support [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config_filename>
+

Required nebari configuration file path

+
+ +
+
+-o, --output <output>
+

output filename

+
+
Default:
+

./nebari-support-logs.zip

+
+
+
+ +
+
+

upgrade

+

Upgrade your [purple]nebari-config.yaml[/purple] from pre-0.4.0 to 0.4.0.

+

Due to several breaking changes that came with the 0.4.0 release, this utility is available to help +update your [purple]nebari-config.yaml[/purple] to comply with the introduced changes. +See the project [green]RELEASE.md[/green] for details.

+
main upgrade [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config>
+

Required nebari configuration file path

+
+ +
+
+--attempt-fixes
+

Attempt to fix the config for any incompatibilities between your old and new Nebari versions.

+
+
Default:
+

False

+
+
+
+ +
+
+

validate

+

Validate the values in the [purple]nebari-config.yaml[/purple] file are acceptable.

+
main validate [OPTIONS]
+
+
+

Options

+
+
+-c, --config <config>
+

Required nebari configuration yaml file path, please pass in as -c/–config flag

+
+ +
+
+--enable-commenting
+

Toggle PR commenting on GitHub Actions

+
+
Default:
+

False

+
+
+
+ +
+
+
+ + +
+ +
+
+ +
+
+
+ ©2023, Nebari. + + | + Powered by Sphinx 6.1.3 + & Alabaster 0.7.13 + + | + Page source +
+ + + + + + \ No newline at end of file diff --git a/docs-sphinx/cli.rst b/docs-sphinx/cli.rst new file mode 100644 index 000000000..b2719f56d --- /dev/null +++ b/docs-sphinx/cli.rst @@ -0,0 +1,6 @@ +Nebari CLI +========== + +.. click:: nebari.cli.main:typer_click_app + :prog: main + :nested: full diff --git a/docs-sphinx/conf.py b/docs-sphinx/conf.py new file mode 100644 index 000000000..ec69d0f7c --- /dev/null +++ b/docs-sphinx/conf.py @@ -0,0 +1,9 @@ +project = 'Nebari CLI documentation' +copyright = '2023, Nebari' +author = 'Nebari team' + +extensions = ['sphinx_click'] + +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +html_theme = 'alabaster' diff --git a/docs-sphinx/index.rst b/docs-sphinx/index.rst new file mode 100644 index 000000000..29e509d9b --- /dev/null +++ b/docs-sphinx/index.rst @@ -0,0 +1,21 @@ +.. Nebari API documentation documentation master file, created by + sphinx-quickstart on Fri Mar 10 12:28:01 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Nebari API documentation's documentation! +==================================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +.. toctree:: + cli + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/pyproject.toml b/pyproject.toml index 264166742..35f71b056 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -82,7 +82,6 @@ dev = [ "pytest-timeout", ] docs = [ - [dev], "sphinx", "sphinx_click", ] From 5da3cc77e137e01dac8c079b68ed87dc993f2680 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Mon, 20 Mar 2023 09:51:31 -0500 Subject: [PATCH 22/28] remove old files --- docs/api_docs/README.md | 28 -- docs/api_docs/api_doc.md | 535 ---------------------------------- docs/api_docs/api_doc_mods.py | 117 -------- docs/api_docs/build.novella | 7 - 4 files changed, 687 deletions(-) delete mode 100644 docs/api_docs/README.md delete mode 100644 docs/api_docs/api_doc.md delete mode 100644 docs/api_docs/api_doc_mods.py delete mode 100644 docs/api_docs/build.novella diff --git a/docs/api_docs/README.md b/docs/api_docs/README.md deleted file mode 100644 index aa3a06028..000000000 --- a/docs/api_docs/README.md +++ /dev/null @@ -1,28 +0,0 @@ -# Nebari API docs - -The Nebari API docs are generated from this repo, then merged into the nebari-docs repo via PR opened by GitHub Actions. - -## Environment - -From the root of the repo: - -```bash -pip install -e ".[docs]" -``` - -## Workflow - -The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI. - -The workflow described below will create the API docs and run a formatting script to do a bit of cleanup. - -```bash -# work out of the api_docs directory in the nebari repo -cd docs/api_docs/ -# auto generate the api docs -pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md -# make formatting modifications and copy into the docs repo -python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md -# run linting and formatting -pre-commit run --files api_doc.md -``` diff --git a/docs/api_docs/api_doc.md b/docs/api_docs/api_doc.md deleted file mode 100644 index d421af4eb..000000000 --- a/docs/api_docs/api_doc.md +++ /dev/null @@ -1,535 +0,0 @@ -______________________________________________________________________ - -## title: API Documentation description: Reference to API docs - -\<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED ---># API Documentation - -## Table of Contents - - - -# nebari.destroy - - - -# nebari.initialize - - - -# nebari.render - - - -#### render_contents - -```python -def render_contents(config: Dict) -``` - -Dynamically generated contents from Nebari configuration - - - -#### gen_gitignore - -```python -def gen_gitignore(config) -``` - -Generate `.gitignore` file. Add files as needed. - - - -#### gen_cicd - -```python -def gen_cicd(config) -``` - -Use cicd schema to generate workflow files based on the `ci_cd` key in the `config`. - -For more detail on schema: GiHub-Actions - nebari/providers/cicd/github.py GitLab-CI - nebari/providers/cicd/gitlab.py - - - -#### inspect_files - -```python -def inspect_files(source_dirs: str, - output_dirs: str, - source_base_dir: str, - output_base_dir: str, - ignore_filenames: List[str] = None, - ignore_directories: List[str] = None, - deleted_paths: List[str] = None, - contents: Dict[str, str] = None) -``` - -Return created, updated and untracked files by computing a checksum over the provided directory - -**Arguments**: - -- `source_dirs` _str_ - The source dir used as base for comparssion -- `output_dirs` _str_ - The destination dir which will be matched with -- `source_base_dir` _str_ - Relative base path to source directory -- `output_base_dir` _str_ - Relative base path to output directory -- `ignore_filenames` _list\[str\]_ - Filenames to ignore while comparing for changes -- `ignore_directories` _list\[str\]_ - Directories to ignore while comparing for changes -- `deleted_paths` _list\[str\]_ - Paths that if exist in output directory should be deleted -- `contents` _dict_ - filename to content mapping for dynamically generated files - - - -#### hash_file - -```python -def hash_file(file_path: str) -``` - -Get the hex digest of the given file - -**Arguments**: - -- `file_path` _str_ - path to file - - - -#### set_env_vars_in_config - -```python -def set_env_vars_in_config(config) -``` - -For values in the config starting with 'NEBARI_SECRET_XXX' the environment variables are searched for the pattern XXX -and the config value is modified. This enables setting secret values that should not be directly stored in the config -file. - -NOTE: variables are most likely written to a file somewhere upon render. In order to further reduce risk of exposure of -any of these variables you might consider preventing storage of the terraform render output. - - - -# nebari.cli - - - -# nebari.cli.keycloak - - - -#### add_user - -```python -@app_keycloak.command(name="adduser") -def add_user(add_users: Tuple[str, str] = typer.Option( - ..., "--user", help="Provide both: "), - config_filename: str = typer.Option( - ..., - "-c", - "--config", - help="nebari configuration file path", - )) -``` - -Add a user to Keycloak. User will be automatically added to the \[italic\]analyst\[/italic\] group. - - - -#### list_users - -```python -@app_keycloak.command(name="listusers") -def list_users(config_filename: str = typer.Option( - ..., - "-c", - "--config", - help="nebari configuration file path", -)) -``` - -List the users in Keycloak. - - - -# nebari.cli.init - - - -#### handle_init - -```python -def handle_init(inputs: InitInputs) -``` - -Take the inputs from the `nebari init` command, render the config and write it to a local yaml file. - - - -#### check_cloud_provider_creds - -```python -def check_cloud_provider_creds(ctx: typer.Context, cloud_provider: str) -``` - -Validate that the necessary cloud credentials have been set as environment variables. - - - -#### check_auth_provider_creds - -```python -def check_auth_provider_creds(ctx: typer.Context, auth_provider: str) -``` - -Validating the the necessary auth provider credentials have been set as environment variables. - - - -#### check_project_name - -```python -def check_project_name(ctx: typer.Context, project_name: str) -``` - -Validate the project_name is acceptable. Depends on `cloud_provider`. - - - -#### guided_init_wizard - -```python -def guided_init_wizard(ctx: typer.Context, guided_init: str) -``` - -Guided Init Wizard is a user-friendly questionnaire used to help generate the `nebari-config.yaml`. - - - -# nebari.cli.main - - - -## OrderCommands Objects - -```python -class OrderCommands(TyperGroup) -``` - - - -#### list_commands - -```python -def list_commands(ctx: Context) -``` - -Return list of commands in the order appear. - - - -#### init - -```python -@app.command() -def init(cloud_provider: str = typer.Argument( - "local", - help=f"options: {enum_to_list(ProviderEnum)}", - callback=check_cloud_provider_creds, - is_eager=True, -), - guided_init: bool = typer.Option( - False, - help=GUIDED_INIT_MSG, - callback=guided_init_wizard, - is_eager=True, - ), - project_name: str = typer.Option( - ..., - "--project-name", - "--project", - "-p", - callback=check_project_name, - ), - domain_name: str = typer.Option( - ..., - "--domain-name", - "--domain", - "-d", - ), - namespace: str = typer.Option("dev", ), - auth_provider: str = typer.Option( - "password", - help=f"options: {enum_to_list(AuthenticationEnum)}", - callback=check_auth_provider_creds, - ), - auth_auto_provision: bool = typer.Option(False, ), - repository: str = typer.Option(None, ), - repository_auto_provision: bool = typer.Option(False, ), - ci_provider: str = typer.Option( - None, - help=f"options: {enum_to_list(CiEnum)}", - ), - terraform_state: str = typer.Option( - "remote", help=f"options: {enum_to_list(TerraformStateEnum)}"), - kubernetes_version: str = typer.Option("latest", ), - ssl_cert_email: str = typer.Option( - None, - callback=check_ssl_cert_email, - ), - disable_prompt: bool = typer.Option( - False, - is_eager=True, - )) -``` - -Create and initialize your \[purple\]nebari-config.yaml\[/purple\] file. - -This command will create and initialize your \[purple\]nebari-config.yaml\[/purple\] :sparkles: - -This file contains all your Nebari cluster configuration details and, is used as input to later commands such as -\[green\]nebari render\[/green\], \[green\]nebari deploy\[/green\], etc. - -If you're new to Nebari, we recommend you use the Guided Init wizard. To get started simply run: - -``` - [green]nebari init --guided-init[/green] -``` - - - -#### validate - -```python -@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) -def validate(config: str = typer.Option( - ..., - "--config", - "-c", - help= - "nebari configuration yaml file path, please pass in as -c/--config flag", -), - enable_commenting: bool = typer.Option( - False, - "--enable-commenting", - help="Toggle PR commenting on GitHub Actions")) -``` - -Validate the values in the \[purple\]nebari-config.yaml\[/purple\] file are acceptable. - - - -#### render - -```python -@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) -def render( - output: str = typer.Option( - "./", - "-o", - "--output", - help="output directory", - ), - config: str = typer.Option( - ..., - "-c", - "--config", - help="nebari configuration yaml file path", - ), - dry_run: bool = typer. - Option( - False, - "--dry-run", - help= - "simulate rendering files without actually writing or updating any files", - )) -``` - -Dynamically render the Terraform scripts and other files from your \[purple\]nebari-config.yaml\[/purple\] file. - - - -#### deploy - -```python -@app.command() -def deploy( - config: str = typer.Option( - ..., - "--config", - "-c", - help="nebari configuration yaml file path", - ), - output: str = typer.Option( - "./", - "-o", - "--output", - help="output directory", - ), - dns_provider: str = typer.Option( - False, - "--dns-provider", - help="dns provider to use for registering domain name mapping", - ), - dns_auto_provision: bool = typer. - Option( - False, - "--dns-auto-provision", - help= - "Attempt to automatically provision DNS, currently only available for `cloudflare`", - ), - disable_prompt: bool = typer.Option( - False, - "--disable-prompt", - help="Disable human intervention", - ), - disable_render: bool = typer.Option( - False, - "--disable-render", - help="Disable auto-rendering in deploy stage", - ), - disable_checks: bool = typer.Option( - False, - "--disable-checks", - help="Disable the checks performed after each stage", - ), - skip_remote_state_provision: bool = typer. - Option( - False, - "--skip-remote-state-provision", - help= - "Skip terraform state deployment which is often required in CI once the terraform remote state bootstrapping phase is complete", - )) -``` - -Deploy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. - - - -#### destroy - -```python -@app.command() -def destroy( - config: str = typer.Option(..., - "-c", - "--config", - help="nebari configuration file path"), - output: str = typer.Option( - "./", - "-o", - "--output", - help="output directory", - ), - disable_render: bool = typer.Option( - False, - "--disable-render", - help="Disable auto-rendering before destroy", - ), - disable_prompt: bool = typer. - Option( - False, - "--disable-prompt", - help= - "Destroy entire Nebari cluster without confirmation request. Suggested for CI use.", - )) -``` - -Destroy the Nebari cluster from your \[purple\]nebari-config.yaml\[/purple\] file. - - - -#### cost - -```python -@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) -def cost(path: str = typer.Option( - None, - "-p", - "--path", - help= - "Pass the path of your stages directory generated after rendering Nebari configurations before deployment", -), - dashboard: bool = typer.Option( - True, - "-d", - "--dashboard", - help="Enable the cost dashboard", - ), - file: str = typer.Option( - None, - "-f", - "--file", - help="Specify the path of the file to store the cost report", - ), - currency: str = typer.Option( - "USD", - "-c", - "--currency", - help="Specify the currency code to use in the cost report", - ), - compare: bool = typer.Option( - False, - "-cc", - "--compare", - help="Compare the cost report to a previously generated report", - )) -``` - -Estimate the cost of deploying Nebari based on your \[purple\]nebari-config.yaml\[/purple\]. -\[italic\]Experimental.\[/italic\] - -\[italic\]This is still only experimental using Infracost under the hood. The estimated value is a base cost and does -not include usage costs.\[/italic\] - - - -#### upgrade - -```python -@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) -def upgrade( - config: str = typer.Option( - ..., - "-c", - "--config", - help="nebari configuration file path", - ), - attempt_fixes: bool = typer. - Option( - False, - "--attempt-fixes", - help= - "Attempt to fix the config for any incompatibilities between your old and new Nebari versions.", - )) -``` - -Upgrade your \[purple\]nebari-config.yaml\[/purple\] from pre-0.4.0 to 0.4.0. - -Due to several breaking changes that came with the 0.4.0 release, this utility is available to help update your -\[purple\]nebari-config.yaml\[/purple\] to comply with the introduced changes. See the project -\[green\]RELEASE.md\[/green\] for details. - - - -#### support - -```python -@app.command(rich_help_panel=SECOND_COMMAND_GROUP_NAME) -def support(config_filename: str = typer.Option( - ..., - "-c", - "--config", - help="nebari configuration file path", -), - output: str = typer.Option( - "./nebari-support-logs.zip", - "-o", - "--output", - help="output filename", - )) -``` - -Support tool to write all Kubernetes logs locally and compress them into a zip file. - -The Nebari team recommends k9s to manage and inspect the state of the cluster. However, this command occasionally -helpful for debugging purposes should the logs need to be shared. diff --git a/docs/api_docs/api_doc_mods.py b/docs/api_docs/api_doc_mods.py deleted file mode 100644 index c31fc8a51..000000000 --- a/docs/api_docs/api_doc_mods.py +++ /dev/null @@ -1,117 +0,0 @@ -from copy import deepcopy -from pathlib import Path - -import click - - -def insert_lines(source_list: list, idx: int, lines: list) -> None: - """Inject a list of lines at a given index""" - lines_r = deepcopy(lines) - lines_r.reverse() - [source_list.insert(idx, line) for line in lines_r] - - -def modify_autogen_api_docs(autogen_path: Path, outpath: Path) -> None: - """Modifications to the auto-generated API docs in order to make them - presentable. - - Args: - autogen_path (Path): path to the autogenerated API docs (*.md) - outpath (Path): output path for the modified docs (*.md) - """ - if not isinstance(autogen_path, Path): - autogen_path = Path(autogen_path) - - if not isinstance(outpath, Path): - outpath = Path(outpath) - - with open(autogen_path) as f: - text = f.readlines() - - header_info = [ - "---\n", - "title: API Documentation\n", - "description: Reference to API docs\n", - "---\n", - "<--- DO NOT EDIT, THIS PAGE IS AUTOGENERATED --->", - "# API Documentation\n", - "## Table of Contents\n", - ] - - # remove Table of contents header - del text[0] - - # insert new header - insert_lines(text, 0, header_info) - - # fix header flags (otherwise page nav won't work) - for idx, line in enumerate(text): - if line[0:7] == "# nebari.": - text[idx] = "##" + line - elif line == "# nebari\n": - text[idx] = "## nebari\n" - - keep_docs = [ - '"nebari.initialize', - '"nebari.cli.deploy', - '"nebari.cli.destroy', - '"nebari.cli.initialize', - '"nebari.cli.render', - '"nebari.cli.support', - '"nebari.cli', - '"nebari.cli.upgrade', - '"nebari.cli.validate', - '"nebari.render', - '"nebari.destroy', - ] - - id_idx = [] - keep_idx = [] - for idx, line in enumerate(text): - if line.startswith(" Date: Mon, 20 Mar 2023 14:53:13 +0000 Subject: [PATCH 23/28] [pre-commit.ci] Apply automatic pre-commit fixes --- docs-sphinx/README.md | 14 +++++++------- docs-sphinx/cli.html | 24 ++++++++++++------------ docs-sphinx/conf.py | 12 ++++++------ nebari/cli/main.py | 1 - 4 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs-sphinx/README.md b/docs-sphinx/README.md index 030519a81..5d0c59e3f 100644 --- a/docs-sphinx/README.md +++ b/docs-sphinx/README.md @@ -1,26 +1,26 @@ # Nebari CLI documentation The CLI docs are generated using Sphinx and the sphinx-click extension. Although -a full Sphinx website is required in order to generate the docs, only the +a full Sphinx website is required in order to generate the docs, only the `cli.html` file is used. This file gets copied over to the nebari-docs repo via -a GitHub Action. +a GitHub Action. ## Automation via GitHub Actions _Generating the CLI HTML file_ A GitHub Action will run with every push to either the `dev` or `main` branches -which generates the documentation. A full Sphinx site build is required. To +which generates the documentation. A full Sphinx site build is required. To build the site, go to the `docs-sphinx` folder and run `make html` -The Action will then checks to see if `cli.html` (the generated doc) has -changed. If it has changed, it will open a new PR with an updated version. +The Action will then checks to see if `cli.html` (the generated doc) has +changed. If it has changed, it will open a new PR with an updated version. _Updating the Nebari Docs repo_ -The Nebari Documentation lives in a separate repo from the code itself +The Nebari Documentation lives in a separate repo from the code itself (https://github.com/nebari-dev/nebari-docs). A separate GitHub Action watches for changes to the `cli.html` file in _this_ repo, and keeps it in sync with -the `cli.html` file in the docs repo. +the `cli.html` file in the docs repo. diff --git a/docs-sphinx/cli.html b/docs-sphinx/cli.html index f2c124a71..f560d8dae 100644 --- a/docs-sphinx/cli.html +++ b/docs-sphinx/cli.html @@ -15,22 +15,22 @@ - + - - + + - +
- +
- +

cli docs

@@ -590,7 +590,7 @@

validate @@ -664,18 +664,18 @@

Quick search

©2023, Nebari. - + | Powered by Sphinx 6.1.3 & Alabaster 0.7.13 - + | Page source
- - + + - \ No newline at end of file + diff --git a/docs-sphinx/conf.py b/docs-sphinx/conf.py index ec69d0f7c..200338f61 100644 --- a/docs-sphinx/conf.py +++ b/docs-sphinx/conf.py @@ -1,9 +1,9 @@ -project = 'Nebari CLI documentation' -copyright = '2023, Nebari' -author = 'Nebari team' +project = "Nebari CLI documentation" +copyright = "2023, Nebari" +author = "Nebari team" -extensions = ['sphinx_click'] +extensions = ["sphinx_click"] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -html_theme = 'alabaster' +html_theme = "alabaster" diff --git a/nebari/cli/main.py b/nebari/cli/main.py index 1aef48c60..901e67cca 100644 --- a/nebari/cli/main.py +++ b/nebari/cli/main.py @@ -78,7 +78,6 @@ def list_commands(self, ctx: Context): ) - @app.callback(invoke_without_command=True) def version( version: Optional[bool] = typer.Option( From bf4e64fee5af3ac2e23461f8710b84de76594202 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Mon, 20 Mar 2023 11:01:23 -0500 Subject: [PATCH 24/28] fix precommit hooks --- .github/workflows/generate_cli_doc.yml | 6 ++--- .pre-commit-config.yaml | 2 ++ docs-sphinx/cli.html | 32 +++++++++++++------------- 3 files changed, 21 insertions(+), 19 deletions(-) diff --git a/.github/workflows/generate_cli_doc.yml b/.github/workflows/generate_cli_doc.yml index e72206a10..765498ad6 100644 --- a/.github/workflows/generate_cli_doc.yml +++ b/.github/workflows/generate_cli_doc.yml @@ -13,7 +13,7 @@ jobs: defaults: run: shell: bash -l {0} - working-directory: ./docs/docs-sphinx + working-directory: ./docs-sphinx steps: - name: Check out repository 🛎️ uses: actions/checkout@v3 @@ -26,7 +26,7 @@ jobs: - name: Install nebari and docs dependencies run: | python -m pip install --upgrade pip - pip install -e "../..[docs]" + pip install -e "../[docs]" - name: Generate new API docs run: | @@ -34,7 +34,7 @@ jobs: - name: Copy cli doc run: | - cp docs-sphinx/_build/html/cli.html docs-sphinx/cli.html + cp _build/html/cli.html cli.html - name: Look for changes to generated docs uses: tj-actions/verify-changed-files@v12 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 42b1a3a8e..65de87b7f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -25,7 +25,9 @@ repos: rev: v4.4.0 hooks: - id: end-of-file-fixer + exclude: "^docs-sphinx/cli.html" - id: trailing-whitespace + exclude: "^docs-sphinx/cli.html" - id: check-json - id: check-yaml # jinja2 templates for helm charts diff --git a/docs-sphinx/cli.html b/docs-sphinx/cli.html index f560d8dae..74ebe0cab 100644 --- a/docs-sphinx/cli.html +++ b/docs-sphinx/cli.html @@ -6,7 +6,7 @@ - cli docs — Nebari CLI documentation documentation + Nebari CLI — Nebari CLI documentation documentation @@ -15,24 +15,24 @@ - + - - + + - +
- +
- -
-

cli docs

+ +
+

Nebari CLI

main

Nebari CLI 🪴

@@ -590,7 +590,7 @@

validate @@ -606,7 +606,7 @@

Nebari CLI documentation

Navigation

©2023, Nebari. - + | Powered by Sphinx 6.1.3 & Alabaster 0.7.13 - + | Page source
+ - - + - + \ No newline at end of file From 385523d783cb21984cbe3d4c221604f48c8c7925 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Fri, 4 Aug 2023 11:44:22 -0500 Subject: [PATCH 25/28] update cli docs --- docs-sphinx/README.md | 4 ++ docs-sphinx/cli.html | 107 ++++++++++------------------------------- docs-sphinx/cli.rst | 2 +- src/nebari/__main__.py | 4 +- 4 files changed, 32 insertions(+), 85 deletions(-) diff --git a/docs-sphinx/README.md b/docs-sphinx/README.md index 5d0c59e3f..36e4941d2 100644 --- a/docs-sphinx/README.md +++ b/docs-sphinx/README.md @@ -5,6 +5,10 @@ a full Sphinx website is required in order to generate the docs, only the `cli.html` file is used. This file gets copied over to the nebari-docs repo via a GitHub Action. +The rich markup is currently unsupported by `sphinx-click` which means that the +color additions to the CLI get explicitly written in the docs +(https://github.com/ewels/rich-click/issues/48). + ## Automation via GitHub Actions _Generating the CLI HTML file_ diff --git a/docs-sphinx/cli.html b/docs-sphinx/cli.html index 74ebe0cab..4a95b718f 100644 --- a/docs-sphinx/cli.html +++ b/docs-sphinx/cli.html @@ -41,66 +41,11 @@

main¶<

Options

-
--v, --version
+
+-V, --version

Nebari version number

-
-

cost

-

Estimate the cost of deploying Nebari based on your [purple]nebari-config.yaml[/purple]. [italic]Experimental.[/italic].

-

[italic]This is still only experimental using Infracost under the hood. -The estimated value is a base cost and does not include usage costs.[/italic]

-
main cost [OPTIONS]
-
-
-

Options

-
-
--p, --path <path>
-

Pass the path of your stages directory generated after rendering Nebari configurations before deployment

-
- -
-
--d, --dashboard
-

Enable the cost dashboard

-
-
Default:
-

True

-
-
-
- -
-
--f, --file <file>
-

Specify the path of the file to store the cost report

-
- -
-
--c, --currency <currency>
-

Specify the currency code to use in the cost report

-
-
Default:
-

USD

-
-
-
- -
-
--cc, --compare
-

Compare the cost report to a previously generated report

-
-
Default:
-

False

-
-
-
- -

deploy

Deploy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file.

@@ -110,17 +55,17 @@

deployOptions

--c, --config <config>
-

Required nebari configuration yaml file path

+-c, --config <config_path> +

Required nebari configuration yaml file path, please pass in as -c/–config flag

--o, --output <output>
+-o, --output <output_path>

output directory

Default:
-

./

+

/Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx

@@ -201,17 +146,17 @@

destroyOptions

--c, --config <config>
-

Required nebari configuration file path

+-c, --config <config_path> +

Required nebari configuration yaml file path, please pass in as -c/–config flag

--o, --output <output>
+-o, --output <output_path>

output directory

Default:
-

./

+

/Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx

@@ -478,19 +423,19 @@

renderOptions

--o, --output <output>
+-o, --output <output_path>

output directory

Default:
-

./

+

/Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx

--c, --config <config>
-

Required nebari configuration yaml file path

+-c, --config <config_path> +

Required nebari configuration yaml file path, please pass in as -c/–config flag

@@ -516,17 +461,17 @@

supportOptions

--c, --config <config_filename>
-

Required nebari configuration file path

+-c, --config <config_path> +

Required nebari configuration yaml file path, please pass in as -c/–config flag

--o, --output <output>
-

output filename

+-o, --output <output_path> +

output directory

Default:
-

./nebari-support-logs.zip

+

/Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx

@@ -534,18 +479,17 @@

support

upgrade

-

Upgrade your [purple]nebari-config.yaml[/purple] from pre-0.4.0 to 0.4.0.

-

Due to several breaking changes that came with the 0.4.0 release, this utility is available to help -update your [purple]nebari-config.yaml[/purple] to comply with the introduced changes. -See the project [green]RELEASE.md[/green] for details.

+

Upgrade your [purple]nebari-config.yaml[/purple].

+

Upgrade your [purple]nebari-config.yaml[/purple] after an nebari upgrade. If necessary, prompts users to perform manual upgrade steps required for the deploy process.

+

See the project [green]RELEASE.md[/green] for details.

main upgrade [OPTIONS]

Options

--c, --config <config>
-

Required nebari configuration file path

+-c, --config <config_path> +

Required nebari configuration yaml file path, please pass in as -c/–config flag

@@ -569,7 +513,7 @@

validateOptions

--c, --config <config>
+-c, --config <config_path>

Required nebari configuration yaml file path, please pass in as -c/–config flag

@@ -608,7 +552,6 @@

Navigation

  • Nebari CLI
    • main
        -
      • cost
      • deploy
      • destroy
      • dev
          diff --git a/docs-sphinx/cli.rst b/docs-sphinx/cli.rst index b2719f56d..269a8dc3d 100644 --- a/docs-sphinx/cli.rst +++ b/docs-sphinx/cli.rst @@ -1,6 +1,6 @@ Nebari CLI ========== -.. click:: nebari.cli.main:typer_click_app +.. click:: _nebari.cli.main:typer_click_app :prog: main :nested: full diff --git a/src/nebari/__main__.py b/src/nebari/__main__.py index 09030b4cb..2b91960bb 100644 --- a/src/nebari/__main__.py +++ b/src/nebari/__main__.py @@ -1,6 +1,6 @@ import sys -from _nebari.cli.main import app as main +from _nebari.cli.main import app as nebari if __name__ == "__main__": - main(sys.argv[1:]) + nebari(sys.argv[1:]) From 9d8ed8a7e6748c813c78a0ff7daf6a5b416e7ada Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 4 Aug 2023 16:44:45 +0000 Subject: [PATCH 26/28] [pre-commit.ci] Apply automatic pre-commit fixes --- docs-sphinx/README.md | 6 +++--- src/_nebari/cli/main.py | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs-sphinx/README.md b/docs-sphinx/README.md index 36e4941d2..9115faede 100644 --- a/docs-sphinx/README.md +++ b/docs-sphinx/README.md @@ -5,9 +5,9 @@ a full Sphinx website is required in order to generate the docs, only the `cli.html` file is used. This file gets copied over to the nebari-docs repo via a GitHub Action. -The rich markup is currently unsupported by `sphinx-click` which means that the -color additions to the CLI get explicitly written in the docs -(https://github.com/ewels/rich-click/issues/48). +The rich markup is currently unsupported by `sphinx-click` which means that the +color additions to the CLI get explicitly written in the docs +(https://github.com/ewels/rich-click/issues/48). ## Automation via GitHub Actions diff --git a/src/_nebari/cli/main.py b/src/_nebari/cli/main.py index 02b293db9..fa63a72c9 100644 --- a/src/_nebari/cli/main.py +++ b/src/_nebari/cli/main.py @@ -430,11 +430,13 @@ def support( print(file) zip.write(file) + # get the click object from the typer app so that we can autodoc the cli # NOTE: this must happen _after_ all the subcommands have been added. # Adapted from https://typer.tiangolo.com/tutorial/using-click/ typer_click_app = typer.main.get_command(app) + def get_config_namespace(config_path): with open(config_path) as f: config = yaml.safe_load(f.read()) From f63fa0f6d330f93ccbc123c1c12abe0cab3b7d13 Mon Sep 17 00:00:00 2001 From: Kim Pevey Date: Tue, 22 Aug 2023 10:22:00 -0500 Subject: [PATCH 27/28] updated for changes to cli --- docs-sphinx/cli.html | 385 ++++++++++++++++++++++++----------------- docs-sphinx/cli.rst | 4 +- src/nebari/__main__.py | 9 +- 3 files changed, 235 insertions(+), 163 deletions(-) diff --git a/docs-sphinx/cli.html b/docs-sphinx/cli.html index 4a95b718f..787118630 100644 --- a/docs-sphinx/cli.html +++ b/docs-sphinx/cli.html @@ -33,47 +33,78 @@

          Nebari CLI

          -
          -

          main

          +
          +

          nebari

          Nebari CLI 🪴

          -
          main [OPTIONS] COMMAND [ARGS]...
+
          nebari [OPTIONS] COMMAND [ARGS]...
 
          
 
          
 
          Options
          
 
          
-
          
--V, --version
          
+
          
+-V, --version
          
 
          Nebari version number
          
 
          
 
-
          
-
          deploy
          
+
          
+
          
+--import-plugin <plugins>
          
+
          Import nebari plugin
          
+
          
+
          Default:
          
+
          
+
          
+
          
+
+
          
+
          
+--exclude-stage <excluded_stages>
          
+
          Exclude nebari stage(s) by name or regex
          
+
          
+
          Default:
          
+
          
+
          
+
          
+
+
          
+
          
+--exclude-default-stages
          
+
          Exclude default nebari included stages
          
+
          
+
          Default:
          
+
          False
          
+
          
+
          
+
          
+
+
          
+
          deploy
          
 
          Deploy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file.
          
-
          main deploy [OPTIONS]
+
          nebari deploy [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_path>
          
-
          Required nebari configuration yaml file path, please pass in as -c/–config flag
          
+
          
+-c, --config <config_filename>
          
+
          Required nebari configuration yaml file path
          
 
          
 
 
          
-
          
--o, --output <output_path>
          
+
          
+-o, --output <output_directory>
          
 
          output directory
          
 
          
 
          Default:
          
-
          /Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx
          
+
          ./
          
 
          
 
          
 
          
 
 
          
-
          
---dns-provider <dns_provider>
          
-
          dns provider to use for registering domain name mapping
          
+
          
+--dns-provider <dns_provider>
          
+
          dns provider to use for registering domain name mapping ⚠️ moved to dns.provider in nebari-config.yaml
          
 
          
 
          Default:
          
 
          False
          
@@ -82,9 +113,9 @@ 
          deploy
-
          
---dns-auto-provision
          
-
          Attempt to automatically provision DNS, currently only available for cloudflare
          
+
          
+--dns-auto-provision
          
+
          Attempt to automatically provision DNS, currently only available for cloudflare ⚠️ moved to dns.auto_provision in nebari-config.yaml
          
 
          
 
          Default:
          
 
          False
          
@@ -93,8 +124,8 @@ 
          deploy
-
          
---disable-prompt
          
+
          
+--disable-prompt
          
 
          Disable human intervention
          
 
          
 
          Default:
          
@@ -104,8 +135,8 @@ 
          deploy
-
          
---disable-render
          
+
          
+--disable-render
          
 
          Disable auto-rendering in deploy stage
          
 
          
 
          Default:
          
@@ -115,8 +146,8 @@ 
          deploy
-
          
---disable-checks
          
+
          
+--disable-checks
          
 
          Disable the checks performed after each stage
          
 
          
 
          Default:
          
@@ -126,8 +157,8 @@ 
          deploy
-
          
---skip-remote-state-provision
          
+
          
+--skip-remote-state-provision
          
 
          Skip terraform state deployment which is often required in CI once the terraform remote state bootstrapping phase is complete
          
 
          
 
          Default:
          
@@ -137,33 +168,33 @@ 
          deploy
-
          destroy
          
+
          
+
          destroy
          
 
          Destroy the Nebari cluster from your [purple]nebari-config.yaml[/purple] file.
          
-
          main destroy [OPTIONS]
+
          nebari destroy [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_path>
          
-
          Required nebari configuration yaml file path, please pass in as -c/–config flag
          
+
          
+-c, --config <config_filename>
          
+
          Required nebari configuration file path
          
 
          
 
 
          
-
          
--o, --output <output_path>
          
+
          
+-o, --output <output_directory>
          
 
          output directory
          
 
          
 
          Default:
          
-
          /Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx
          
+
          ./
          
 
          
 
          
 
          
 
 
          
-
          
---disable-render
          
+
          
+--disable-render
          
 
          Disable auto-rendering before destroy
          
 
          
 
          Default:
          
@@ -173,8 +204,8 @@ 
          destroy
-
          
---disable-prompt
          
+
          
+--disable-prompt
          
 
          Destroy entire Nebari cluster without confirmation request. Suggested for CI use.
          
 
          
 
          Default:
          
@@ -184,37 +215,43 @@ 
          destroy
-
          dev
          
+
          
+
          dev
          
 
          Development tools and advanced features.
          
-
          main dev [OPTIONS] COMMAND [ARGS]...
+
          nebari dev [OPTIONS] COMMAND [ARGS]...
 
          
 
          
-
          
-
          keycloak-api
          
+
          
+
          keycloak-api
          
 
          Interact with the Keycloak REST API directly.
          
 
          This is an advanced tool which can have potentially destructive consequences.
 Please use this at your own risk.
          
-
          main dev keycloak-api [OPTIONS]
+
          nebari dev keycloak-api [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_filename>
          
+
          
+-c, --config <config_filename>
          
 
          Required nebari configuration file path
          
 
          
 
 
          
-
          
--r, --request <request>
          
+
          
+-r, --request <request>
          
 
          Required Send a REST API request, valid requests follow patterns found here: [green]keycloak.org/docs-api/15.0/rest-api[/green]
          
 
          
 
 
          
 
          
-
          
-
          init
          
+
          
+
          info
          
+
          nebari info [OPTIONS]
+
          
+
          
+
          
+
          
+
          init
          
 
          Create and initialize your [purple]nebari-config.yaml[/purple] file.
          
 
          This command will create and initialize your [purple]nebari-config.yaml[/purple] :sparkles:
          
 
          This file contains all your Nebari cluster configuration details and,
@@ -224,13 +261,13 @@ 
          init
          main init [OPTIONS] [CLOUD_PROVIDER]
+
          nebari init [OPTIONS] [CLOUD_PROVIDER]:[local|existing|do|aws|gcp|azure]
 
          
 
          
 
          Options
          
 
          
-
          
---guided-init, --no-guided-init
          
+
          
+--guided-init, --no-guided-init
          
 
          [bold green]START HERE[/bold green] - this will guide you step-by-step to generate your [purple]nebari-config.yaml[/purple]. It is an [i]alternative[/i] to passing the options listed below.
          
 
          
 
          Default:
          
@@ -240,20 +277,19 @@ 
          init
-
          
--p, --project-name, --project <project_name>
          
+
          
+-p, --project-name, --project <project_name>
          
 
          Required
          
 
          
 
 
          
-
          
--d, --domain-name, --domain <domain_name>
          
-
          Required
          
-
          
+
          
+-d, --domain-name, --domain <domain_name>
          
+
          
 
 
          
-
          
---namespace <namespace>
          
+
          
+--namespace <namespace>
          
 
          
 
          Default:
          
 
          dev
          
@@ -262,19 +298,22 @@ 
          init
-
          
---auth-provider <auth_provider>
          
-
          options: [‘password’, ‘github’, ‘auth0’, ‘custom’]
          
+
          
+--auth-provider <auth_provider>
          
+
          options: [‘password’, ‘GitHub’, ‘Auth0’, ‘custom’]
          
 
          
 
          Default:
          
-
          password
          
+
          AuthenticationEnum.password
          
+
          
+
          Options:
          
+
          password | GitHub | Auth0 | custom
          
 
          
 
          
 
          
 
 
          
-
          
---auth-auto-provision, --no-auth-auto-provision
          
+
          
+--auth-auto-provision, --no-auth-auto-provision
          
 
          
 
          Default:
          
 
          False
          
@@ -283,14 +322,19 @@ 
          init
-
          
---repository <repository>
          
+
          
+--repository <repository>
          
 
          options: [‘github.com’, ‘gitlab.com’]
          
+
          
+
          Options:
          
+
          github.com | gitlab.com
          
+
          
+
          
 
          
 
 
          
-
          
---repository-auto-provision, --no-repository-auto-provision
          
+
          
+--repository-auto-provision, --no-repository-auto-provision
          
 
          
 
          Default:
          
 
          False
          
@@ -299,25 +343,36 @@ 
          init
-
          
---ci-provider <ci_provider>
          
+
          
+--ci-provider <ci_provider>
          
 
          options: [‘github-actions’, ‘gitlab-ci’, ‘none’]
          
+
          
+
          Default:
          
+
          CiEnum.none
          
+
          
+
          Options:
          
+
          github-actions | gitlab-ci | none
          
+
          
+
          
 
          
 
 
          
-
          
---terraform-state <terraform_state>
          
+
          
+--terraform-state <terraform_state>
          
 
          options: [‘remote’, ‘local’, ‘existing’]
          
 
          
 
          Default:
          
-
          remote
          
+
          TerraformStateEnum.remote
          
+
          
+
          Options:
          
+
          remote | local | existing
          
 
          
 
          
 
          
 
 
          
-
          
---kubernetes-version <kubernetes_version>
          
+
          
+--kubernetes-version <kubernetes_version>
          
 
          
 
          Default:
          
 
          latest
          
@@ -326,13 +381,13 @@ 
          init
-
          
---ssl-cert-email <ssl_cert_email>
          
+
          
+--ssl-cert-email <ssl_cert_email>
          
 
          
 
 
          
-
          
---disable-prompt, --no-disable-prompt
          
+
          
+--disable-prompt, --no-disable-prompt
          
 
          
 
          Default:
          
 
          False
          
@@ -340,56 +395,67 @@ 
          init
+
          
+-o, --output <output>
          
+
          Output file path for the rendered config file.
          
+
          
+
          Default:
          
+
          nebari-config.yaml
          
+
          
+
          
+
          
+
 
          Arguments
          
 
          
-
          
-CLOUD_PROVIDER
          
+
          
+CLOUD_PROVIDER
          
 
          Optional argument
          
 
          
 
 
          
-
          
-
          keycloak
          
+
          
+
          keycloak
          
 
          Interact with the Nebari Keycloak identity and access management tool.
          
-
          main keycloak [OPTIONS] COMMAND [ARGS]...
+
          nebari keycloak [OPTIONS] COMMAND [ARGS]...
 
          
 
          
-
          
-
          adduser
          
+
          
+
          adduser
          
 
          Add a user to Keycloak. User will be automatically added to the [italic]analyst[/italic] group.
          
-
          main keycloak adduser [OPTIONS]
+
          nebari keycloak adduser [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
---user <add_users>
          
+
          
+--user <add_users>
          
 
          Required Provide both: <username> <password>
          
 
          
 
 
          
-
          
--c, --config <config_filename>
          
+
          
+-c, --config <config_filename>
          
 
          Required nebari configuration file path
          
 
          
 
 
          
-
          
-
          export-users
          
+
          
+
          export-users
          
 
          Export the users in Keycloak.
          
-
          main keycloak export-users [OPTIONS]
+
          nebari keycloak export-users [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_filename>
          
+
          
+-c, --config <config_filename>
          
 
          Required nebari configuration file path
          
 
          
 
 
          
-
          
---realm <realm>
          
+
          
+--realm <realm>
          
 
          realm from which users are to be exported
          
 
          
 
          Default:
          
@@ -399,48 +465,48 @@ 
          export-users
-
          listusers
          
+
          
+
          listusers
          
 
          List the users in Keycloak.
          
-
          main keycloak listusers [OPTIONS]
+
          nebari keycloak listusers [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_filename>
          
+
          
+-c, --config <config_filename>
          
 
          Required nebari configuration file path
          
 
          
 
 
          
 
          
-
          
-
          render
          
+
          
+
          render
          
 
          Dynamically render the Terraform scripts and other files from your [purple]nebari-config.yaml[/purple] file.
          
-
          main render [OPTIONS]
+
          nebari render [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--o, --output <output_path>
          
+
          
+-o, --output <output_directory>
          
 
          output directory
          
 
          
 
          Default:
          
-
          /Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx
          
+
          ./
          
 
          
 
          
 
          
 
 
          
-
          
--c, --config <config_path>
          
-
          Required nebari configuration yaml file path, please pass in as -c/–config flag
          
+
          
+-c, --config <config_filename>
          
+
          Required nebari configuration yaml file path
          
 
          
 
 
          
-
          
---dry-run
          
+
          
+--dry-run
          
 
          simulate rendering files without actually writing or updating any files
          
 
          
 
          Default:
          
@@ -450,51 +516,51 @@ 
          render
-
          support
          
+
          
+
          support
          
 
          Support tool to write all Kubernetes logs locally and compress them into a zip file.
          
 
          The Nebari team recommends k9s to manage and inspect the state of the cluster.
 However, this command occasionally helpful for debugging purposes should the logs need to be shared.
          
-
          main support [OPTIONS]
+
          nebari support [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_path>
          
-
          Required nebari configuration yaml file path, please pass in as -c/–config flag
          
+
          
+-c, --config <config_filename>
          
+
          Required nebari configuration file path
          
 
          
 
 
          
-
          
--o, --output <output_path>
          
-
          output directory
          
+
          
+-o, --output <output>
          
+
          output filename
          
 
          
 
          Default:
          
-
          /Users/kcp/projects/nebari/git/api_docs_final/docs-sphinx
          
+
          ./nebari-support-logs.zip
          
 
          
 
          
 
          
 
 
          
-
          
-
          upgrade
          
+
          
+
          upgrade
          
 
          Upgrade your [purple]nebari-config.yaml[/purple].
          
 
          Upgrade your [purple]nebari-config.yaml[/purple] after an nebari upgrade. If necessary, prompts users to perform manual upgrade steps required for the deploy process.
          
 
          See the project [green]RELEASE.md[/green] for details.
          
-
          main upgrade [OPTIONS]
+
          nebari upgrade [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_path>
          
-
          Required nebari configuration yaml file path, please pass in as -c/–config flag
          
+
          
+-c, --config <config_filename>
          
+
          Required nebari configuration file path
          
 
          
 
 
          
-
          
---attempt-fixes
          
+
          
+--attempt-fixes
          
 
          Attempt to fix the config for any incompatibilities between your old and new Nebari versions.
          
 
          
 
          Default:
          
@@ -504,22 +570,22 @@ 
          upgrade
-
          validate
          
+
          
+
          validate
          
 
          Validate the values in the [purple]nebari-config.yaml[/purple] file are acceptable.
          
-
          main validate [OPTIONS]
+
          nebari validate [OPTIONS]
 
          
 
          
 
          Options
          
 
          
-
          
--c, --config <config_path>
          
+
          
+-c, --config <config_filename>
          
 
          Required nebari configuration yaml file path, please pass in as -c/–config flag
          
 
          
 
 
          
-
          
---enable-commenting
          
+
          
+--enable-commenting
          
 
          Toggle PR commenting on GitHub Actions
          
 
          
 
          Default:
          
@@ -551,24 +617,25 @@ 
          Nebari CLI documentation
          
 
          Navigation
          
 
            
 
          • Nebari CLI
              
-
            • main
                
-
              • deploy
                • 
-
              • destroy
                • 
-
              • dev
                  
-
                • keycloak-api
                  • 
+
                • nebari
diff --git a/docs-sphinx/cli.rst b/docs-sphinx/cli.rst
index 269a8dc3d..68decbaad 100644
--- a/docs-sphinx/cli.rst
+++ b/docs-sphinx/cli.rst
@@ -1,6 +1,6 @@
 Nebari CLI
 ==========
 
-.. click:: _nebari.cli.main:typer_click_app
-   :prog: main
+.. click:: nebari.__main__:typer_click_app
+   :prog: nebari
    :nested: full
diff --git a/src/nebari/__main__.py b/src/nebari/__main__.py
index ef4e8dfb3..c6ce3da4f 100644
--- a/src/nebari/__main__.py
+++ b/src/nebari/__main__.py
@@ -1,4 +1,5 @@
 from _nebari.cli import create_cli
+import typer
 
 
 def main():
@@ -6,6 +7,10 @@ def main():
     cli()
 
 
-if __name__ == "__main__":
-    main()
+# get the click object from the typer app so that we can autodoc the cli
+# NOTE: this must happen _after_ all the subcommands have been added.
+# Adapted from https://typer.tiangolo.com/tutorial/using-click/
+typer_click_app = typer.main.get_command(create_cli())
 
+if __name__ == "__main__":
+    typer_click_app()

From b8b269fc91f25e4cf42418f17d1013c898f868fc Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Tue, 22 Aug 2023 15:22:27 +0000
Subject: [PATCH 28/28] [pre-commit.ci] Apply automatic pre-commit fixes

---
 src/nebari/__main__.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/nebari/__main__.py b/src/nebari/__main__.py
index c6ce3da4f..2bf6e19bb 100644
--- a/src/nebari/__main__.py
+++ b/src/nebari/__main__.py
@@ -1,6 +1,7 @@
-from _nebari.cli import create_cli
 import typer
 
+from _nebari.cli import create_cli
+
 
 def main():
     cli = create_cli()