fix(docs): Fix documentation structure and content (#21)

.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:

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.

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 <spec version number>`: Deploy a specific version from the spec
+  file.
+- `envers draft <spec version number>`: Create a new version draft in the spec
+  file. Some variants of this command:
+  - `envers draft <spec version number> --from <previous spec version number>`
+  - `envers draft <spec version number> --from-env .env`
+- `envers profile-set --profile <profile_name> --spec <version_number>`: Add new
+  content.
+- `envers profile load --profile prod --spec <spec version>`: 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

docs/mkdocs.yaml → 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

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"