diff --git a/.makim.yaml b/.makim.yaml index 5488058..adcec86 100644 --- a/.makim.yaml +++ b/.makim.yaml @@ -25,14 +25,12 @@ groups: build: help: Build documentation run: | - mkdocs build --config-file docs/mkdocs.yaml + mkdocs build --config-file mkdocs.yaml preview: help: Preview documentation page locally - dependencies: - - task: docs.build run: | - mkdocs build --config-file docs/mkdocs.yaml + mkdocs serve --watch docs --config-file mkdocs.yaml tests: env: diff --git a/README.md b/README.md index 4f041c4..8791e1d 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,6 @@ for version `1.0`. ## Roadmap -- Integration with Ansible Vault for encryption. - Detailed spec and content management functionalities. - Enhancements in versioning and group management. - Integration with makim and sugar. diff --git a/docs/api/references.md b/docs/api/references.md deleted file mode 100644 index fd18567..0000000 --- a/docs/api/references.md +++ /dev/null @@ -1,3 +0,0 @@ -# Api references - -::: envers diff --git a/docs/api/references.rst b/docs/api/references.rst deleted file mode 100644 index ddb3d8a..0000000 --- a/docs/api/references.rst +++ /dev/null @@ -1,8 +0,0 @@ -API references -============== - -.. automodule:: envers - :members: - -.. automodule:: envers.envers - :members: diff --git a/docs/images/logo-big.png b/docs/images/logo-big.png new file mode 100644 index 0000000..4ce9ddf Binary files /dev/null and b/docs/images/logo-big.png differ diff --git a/docs/images/logo.png b/docs/images/logo.png index e80a40e..4f92535 100644 Binary files a/docs/images/logo.png and b/docs/images/logo.png differ diff --git a/docs/index.md b/docs/index.md index 8afdf37..8791e1d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,39 +1,131 @@ -![LOGO](/images/logo.png) - # Envers -Envers is a tool for handling environment files (e.g. .env) for multiple kind of -environments with versioning - -- License: BSD 3 Clause -- Documentation: https://envers.github.io +`Envers` is a command-line tool (CLI) designed to manage and version environment +variables for different deployment stages such as staging, development, and +production. It provides a secure and organized way to handle +environment-specific configurations. ## Features -- The security of our code: Bandit is a powerful tool that we use in our Python - project to ensure its security. This tool analyzes the code and detects - potential vulnerabilities. Some of the key features of Bandit are its ease of - use, its ability to integrate with other tools, and its support for multiple - Python versions. If you want to know about bandit you can check its - [documentation](https://bandit.readthedocs.io/en/latest/). - -- Finds unused code: [Vulture](https://github.com/jendrikseipp/vulture) is - useful for cleaning up and finding errors in large code bases in Python. - -- Complexity of functions and modules: We use - [McCabe](https://github.com/PyCQA/mccabe) to identify the complexity in our - Python code that may be difficult to maintain or understand. By identifying - complex code at the outset, we as developers can refactor it to make it easier - to maintain and understand. In summary, McCabe helps us to improve the quality - of our code and make it easier to maintain. If you would like to learn more - about McCabe and code complexity, you can visit - [McCabe - Code Complexity Checker](https://here-be-pythons.readthedocs.io/en/latest/python/mccabe.html). - This tool is included with [Flake8](https://flake8.pycqa.org/en/latest/). - -- TODO - -## Credits - -This package was created with Cookieninja and the -[osl-incubator/scicookie](https://github.com/osl-incubator/scicookie) project -template. +- Encrypt environment variables: Creates encrypted files that store environment + variables that can be safely stored in a git repository +- Group-Based Configurations: Allows defining variables for different + groups/profiles like prod, dev, etc. +- File-Based Variable Definitions: Supports multiple environment files (.env) + with specific variables for each file. +- CLI-Driven: Provide CLI commands that helps to create drafts for environment + variables and deploy it to encrypted files +- Spec Management: Each release has a defined spec that applies to all + groups/profiles within that release. +- Environment File Generation: Enables generating .env files for specific + versions and groups/profiles using commands. + +## Installation + +TBD + +## Usage + +Below are the initial subcommands for `envers`: + +- `envers init`: Initialize the `envers` environment. +- `envers deploy `: Deploy a specific version from the spec + file. +- `envers draft `: Create a new version draft in the spec + file. Some variants of this command: + - `envers draft --from ` + - `envers draft --from-env .env` +- `envers profile-set --profile --spec `: Add new + content. +- `envers profile load --profile prod --spec `: Load a specific + environment profile to files + +`envers init` creates the spec file at `.envers/.specs.yaml`. + +`envers deploy` creates the file `.envers/.data.lock`. This file is +auto-generated by `envers` command, and it is encrypted. + +The initial version of `./.envers/.specs.yaml` would look like this: + +```yaml +version: 0.1 # the envers spec version +releases: +``` + +As you can see, it doesn't have too much information. If you want to draft a new +version, you can run the following command: + +```bash +$ envers draft 1.0 +``` + +After this command, the `.envers/specs.yaml` file should look like this: + +```yaml +version: 0.1 # the spec version +releases: + # placeholder: the version for the environment variables. + # if the status is draft, feel free to change the version number + 1.0: + # status attribute is handled by command line, don't change it manually + status: draft # options are: draft, cancelled, deployed + # placeholder: update help with the real help text + help: + # placeholder: a list of available profiles (groups) for this version. + # at least one profile is required for the deploying + profiles: + - base + # define the spec for that version, this spec should be used for all + # profiles (groups) inside this version + spec: + # define the env file or any other kind of environment file to be used, + # for now it just has support for .env files + files: + # placeholder: change `.env` to the correct dotenv file relative path + .env: + type: dotenv # default + # `vars` is a dictionary for the environment variables + # this defines the variables and some metadata, but not the real + # value, because it is just the definition of the spec. + vars: + # placeholder: ENV is just a variable name, replace it by your real + # environment variable + ENV: + type: string # options are: string, int, bool, path + default: dev # in the case that the variable is not defined +``` + +Now, you can deploy your first version of environment variables: + +```bash +$ envers deploy 1.0 +``` + +When a version is deployed, it creates automatically all the new spec into the +`.envers/data.lock`. + +All the variables for the each profile and spec version is stored into +`.envers/data.lock`, and this file shouldn't be changed for any reason. + +Finally, we can create the environment variables for the `base` profile: + +```bash +$ envers profile set --profile base --spec 1.0 +``` + +`envers` will ask you via prompt the value for each variable defined in the spec +for version `1.0`. + +## Roadmap + +- Detailed spec and content management functionalities. +- Enhancements in versioning and group management. +- Integration with makim and sugar. + +## Contributing + +https://osl-incubator.github.io/envers + +## License + +BSD-Clause 3 diff --git a/docs/mkdocs.yaml b/mkdocs.yaml similarity index 64% rename from docs/mkdocs.yaml rename to mkdocs.yaml index 1f4544a..f0a0520 100644 --- a/docs/mkdocs.yaml +++ b/mkdocs.yaml @@ -1,8 +1,8 @@ site_name: Envers site_url: https://osl-incubator.github.io/envers repo_url: https://github.com/osl-incubator/envers -docs_dir: ./ -site_dir: ../build +docs_dir: ./docs +site_dir: ./build # extra_css: # - stylesheets/extra.css # Page tree @@ -11,7 +11,8 @@ nav: - Installation: installation.md - Changelog: changelog.md - Contributing: contributing.md - - API: api/references.md + # from gen-files + - API: api/ - Notebook page: example.ipynb theme: name: material @@ -26,8 +27,8 @@ theme: - search.suggest icon: repo: fontawesome/brands/github - logo: /images/logo.png - favicon: /images/favicon.png + logo: ./images/logo.png + favicon: ./images/favicon.png palette: scheme: slate primary: white @@ -36,10 +37,15 @@ theme: plugins: - search - macros - # - autorefs + - autorefs # - exclude: # glob: # - backends/template.md + - gen-files: + scripts: + - scripts/gen_ref_nav.py + - literate-nav: + nav_file: SUMMARY.md - mkdocstrings: enable_inventory: true handlers: @@ -49,52 +55,33 @@ plugins: import: - https://docs.python.org/3/objects.inv options: + docstring_options: + ignore_init_summary: true + docstring_section_style: list docstring_style: numpy - filters: - - "!^Bounds" - - "!^__class__" - - "!^_filter_with_like" - - "!^_find_backends" - - "!^_key$" - - "!^_literal_value_hash_key" - - "!^_log" - - "!^_nbytes" - - "!^_safe_name$" - - "!^_schema_from_csv" - - "!^_to_geodataframe" - - "!^_tuplize" - - "!^ast_schema" - - "!^backend_table_type" - - "!^bounds$" - - "!^column$" - - "!^compiler$" - - "!^context_class" - - "!^database_class" - - "!^do_connect" - - "!^fetch_from_cursor" - - "!^get_schema" - - "!^largest$" - - "!^reconnect" - - "!^select_builder_class" - - "!^select_class" - - "!^table_class$" - - "!^table_expr_class" - - "!^translator_class" - - "!^Options$" - show_category_heading: true + filters: ["!^_"] + heading_level: 1 + inherited_members: true + merge_init_into_class: true + separate_signature: true + # show_category_heading: true + # show_modules: true show_root_full_path: false show_root_heading: true - show_root_toc_entry: true - show_source: false - show_modules: true + # show_root_toc_entry: true + show_signature_annotations: true + show_source: true + show_symbol_type_heading: true + show_symbol_type_toc: true + signature_crossrefs: true + summary: true - mkdocs-jupyter: - execute: true + execute: false ignore: - "*.py" - # execute_ignore: "tutorial/*Geospatial*.ipynb" + - ".ipynb_checkpoints/*" include_source: true - theme: dark - - literate-nav + include_requirejs: true markdown_extensions: - admonition - attr_list @@ -110,8 +97,10 @@ markdown_extensions: custom_icons: - docs/static/icons - pymdownx.details - - pymdownx.highlight - - pymdownx.inlinehilite + - pymdownx.highlight: + pygments_lang_class: true + - pymdownx.inlinehilite: + style_plain_text: python - pymdownx.magiclink: provider: github repo_url_shortener: true diff --git a/poetry.lock b/poetry.lock index c429e65..18c5d78 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1386,6 +1386,20 @@ files = [ [package.dependencies] mkdocs = "*" +[[package]] +name = "mkdocs-gen-files" +version = "0.5.0" +description = "MkDocs plugin to programmatically generate documentation pages during the build" +optional = false +python-versions = ">=3.7" +files = [ + {file = "mkdocs_gen_files-0.5.0-py3-none-any.whl", hash = "sha256:7ac060096f3f40bd19039e7277dd3050be9a453c8ac578645844d4d91d7978ea"}, + {file = "mkdocs_gen_files-0.5.0.tar.gz", hash = "sha256:4c7cf256b5d67062a788f6b1d035e157fc1a9498c2399be9af5257d4ff4d19bc"}, +] + +[package.dependencies] +mkdocs = ">=1.0.3" + [[package]] name = "mkdocs-get-deps" version = "0.2.0" @@ -1516,6 +1530,7 @@ Markdown = ">=3.6" MarkupSafe = ">=1.1" mkdocs = ">=1.4" mkdocs-autorefs = ">=1.2" +mkdocstrings-python = {version = ">=0.5.2", optional = true, markers = "extra == \"python\""} platformdirs = ">=2.2" pymdown-extensions = ">=6.3" typing-extensions = {version = ">=4.1", markers = "python_version < \"3.10\""} @@ -3067,4 +3082,4 @@ type = ["pytest-mypy"] [metadata] lock-version = "2.0" python-versions = ">=3.8.1,<4" -content-hash = "231a07ee5285aca345036da697c0f072b1057c5f563ccb2735646a7c21c1719d" +content-hash = "e90044e2f15a9bf8d0f83e427ffa3609b700cf3e41a17090cb35c35a490c879d" diff --git a/pyproject.toml b/pyproject.toml index 6aed41d..786fbe2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,7 +46,8 @@ mkdocs-jupyter = ">=0.24.1" mkdocs-literate-nav = ">=0.6.0" mkdocs-macros-plugin = ">=0.7.0,<1" mkdocs-material = ">=9.1.15" -mkdocstrings = ">=0.21.2" +mkdocstrings = {version=">=0.24.3", extras=["python"]} +mkdocs-gen-files = ">=0.5.0" mkdocstrings-python = ">=1.1.2" makim ="1.16.0"